## What was done
1. **TIMMY_NOSTR_NSEC secret set** — Generated a permanent Nostr keypair and the user set
it as a Replit secret. Timmy's identity is now stable across restarts:
npub1e3gu2j08t6hymjd5sz9dmy4u5pcl22mj5hl60avkpj5tdpaq3dasjax6tv
2. **app.ts — Fixed import.meta.url for CJS production bundle**
esbuild CJS bundles set import.meta={} (empty), crashing the Tower static path resolution.
Fixed with try/catch: ESM dev mode uses import.meta.url (3 levels up from src/); CJS prod
bundle falls back to process.cwd() + "the-matrix/dist" (workspace root assumption correct
since run command is issued from workspace root).
3. **routes/index.ts — Stub-mode-aware dev route gating**
Changed condition from `NODE_ENV !== "production"` to
`NODE_ENV !== "production" || lnbitsService.stubMode`.
The testkit relies on POST /dev/stub/pay/:hash to simulate Lightning payments. Previously
this endpoint was hidden in production even when LNbits was in stub mode, causing FAIL=5.
Now: real production with real LNbits → stubMode=false → dev routes unexposed (secure).
Production bundle with stub LNbits → stubMode=true → dev routes exposed → testkit passes.
4. **artifact.toml — deploymentTarget = "vm"** set so the artifact deploys always-on.
The .replit file cannot be edited directly via available APIs; artifact.toml takes
precedence for this artifact's deployment configuration.
5. **Production bundle rebuilt** (dist/index.cjs, 1.6MB) — clean build, no warnings.
6. **Full testkit against production bundle in stub mode: PASS=40/41 FAIL=0 SKIP=1**
(SKIP=1 is the Nostr challenge/sign/verify test which requires nostr-tools in bash, same
baseline as dev mode).
## Deployment command
Build: pnpm --filter @workspace/api-server run build
Run: node artifacts/api-server/dist/index.cjs
Health: /api/healthz
Target: VM (always-on) — required for WebSocket connections and in-memory world state.
## Original task
Validate and fix the Expo mobile app (Face/Matrix/Feed tabs) against the live API server.
Restart the API server (was EADDRINUSE from prior merge), verify domain config, test all three tabs, fix issues, and confirm TypeScript typecheck passes.
## Changes made
### artifacts/mobile/app/(tabs)/matrix.tsx
- Fixed getMatrixUrl(): was returning `https://{domain}/` (API landing page), now returns `https://{domain}/tower` (Three.js 3D world). This was the main UI bug — the Matrix tab was showing the wrong page.
### artifacts/api-server/src/app.ts
- Fixed tower static file path: replaced `path.resolve(process.cwd(), "the-matrix", "dist")` with `path.resolve(__dirname_app, "../../..", "the-matrix", "dist")` using `fileURLToPath(import.meta.url)`.
- Root cause: pnpm `--filter` runs scripts from the package directory (`artifacts/api-server`), so `process.cwd()` resolved to `artifacts/api-server/the-matrix/dist` (missing), not `the-matrix/dist` at workspace root. This caused /tower to 404 in development.
- The import.meta.url approach works correctly in both dev (tsx from src/) and production (esbuild CJS bundle from dist/) since both are 3 levels deep from workspace root.
### Infrastructure
- Killed stale process on port 18115, restarted Expo workflow (was stuck waiting for port with interactive prompt).
- Restarted API server (was EADDRINUSE from prior task merge).
## Verification
- API healthz returns 200, /tower/ returns 200.
- TypeScript typecheck passes for @workspace/mobile (no errors).
- TypeScript typecheck passes for @workspace/api-server (no errors).
- Expo dev server running on port 18115, Metro bundler active.
- WebSocket connections visible in API server logs (clients connected).
- EXPO_PUBLIC_DOMAIN set to $REPLIT_DEV_DOMAIN in dev script (correct for wss:// and https:// connections).
Baked Timmy's anti-walled-garden, open-source identity into all AI system
prompts across artifacts/api-server/src/lib/agent.ts and engagement.ts.
Changes:
1. chatReply prompt — Extended wizard persona to include open-source ethos
("AI Johnny Appleseed", seeds scattered freely, not walled gardens).
Added an explicit EXCEPTION section for self-hosting requests — brevity
rule is suspended and a full practical rundown is given (pnpm monorepo,
stack, env vars, startup command). No hedging, no upselling hosted version.
Also bumped max_tokens from 150 → 400 so self-hosting replies are not
hard-truncated, and removed the 250-char slice() from the return value.
2. executeWork and executeWorkStreaming prompts — Same open ethos and full
self-hosting reference added so paid job self-hosting requests get
identical, accurate guidance. Both prompts are kept in sync.
3. evaluateRequest prompt — Added an explicit ALWAYS ACCEPT rule for
self-hosting, open-source, and "how do I run this myself" requests so they
are never treated as edge cases or rejected.
4. Nostr outreach prompt (engagement.ts) — Lightly updated to include
Timmy's open/self-sovereign identity and allow optional open-source mention
when it fits naturally; tone stays warm and non-pushy.
No UI changes, no schema changes, no payment logic touched.
Replit-Task-Id: 4a4a7219-88aa-4a4e-8490-6f7c17e8adfb
import.meta.url is undefined when esbuild bundles to CJS format
(format: 'cjs' in build.ts). fileURLToPath(undefined) throws
ERR_INVALID_ARG_TYPE which crashed the production server on startup.
Fix: drop the _dirname derivation entirely and resolve TIMMY_TEST_PLAN.md
relative to process.cwd(), which is always the workspace root in both:
- dev: tsx runs from workspace root
- production: pnpm --filter ... run start runs from workspace root
Also removes the now-unused 'dirname' and 'fileURLToPath' imports.
Verified: rebuilt dist/index.cjs — 0 import.meta.url references remain.
GET /api/testkit/plan returns HTTP 200 from the production bundle.
## 12 new tests added to artifacts/api-server/src/routes/testkit.ts
Inserted before the Summary block, after T24 (cost ledger).
T25 — POST /identity/challenge: HTTP 200, nonce=64-char hex, expiresAt=ISO
T26 — POST /identity/verify {}: HTTP 400, non-empty error
T27 — POST /identity/verify fake nonce: HTTP 401, error contains "Nonce not found"
(uses a plausible-looking event structure to hit the nonce check, not the
signature check — tests the right layer)
T28 — GET /identity/me no header: HTTP 401, error contains "Missing"
T29 — GET /identity/me invalid token: HTTP 401 (Invalid/expired wording)
T30 — POST /sessions bad X-Nostr-Token: HTTP 401, "Invalid or expired", no sessionId
T31 — POST /jobs bad X-Nostr-Token: HTTP 401, "Invalid or expired"
T32 — POST /sessions anonymous: HTTP 201, trust_tier="anonymous"; captures T32_SESSION_ID
T33 — POST /jobs anonymous: HTTP 201, trust_tier="anonymous"; captures T33_JOB_ID
T34 — GET /jobs/:id (using T33_JOB_ID): HTTP 200, trust_tier non-null and "anonymous"
T35 — GET /sessions/:id (using T32_SESSION_ID): HTTP 200, trust_tier="anonymous"
T36 — Full challenge→sign→verify E2E: inline node CJS script generates ephemeral secp256k1
keypair via nostr-tools CJS bundle, POSTs challenge, signs kind=27235 event with
finalizeEvent(), verifies → nostr_token, GETs /identity/me, asserts tier=new,
interactionCount=0, pubkey matches. Guard: SKIP if node not in PATH or script fails.
## nostr-tools import strategy
nostr-tools v2 is ESM-only. CJS workaround: the package ships a CJS bundle at
lib/cjs/index.js. T36 uses require() with the absolute path to that bundle.
Falls back to bare require('nostr-tools') for portability, exits with code 1 if
neither works — bash guard catches this and marks T36 SKIP (not FAIL).
## Stubs T37–T40 added as bash block comments after T36
Format: `# FUTURE T3N: <description>` so they are grepped easily.
Covers: GET /api/estimate (cost preview), anonymous Lightning gate, trusted free tier,
Timmy-initiates-zap. Does not affect PASS/FAIL totals.
## TIMMY_TEST_PLAN.md updated
New "Nostr identity + trust engine (tests 25–36)" section added to the test table.
## TypeScript: 0 errors. All 12 tests smoke-tested individually against localhost:8080.
T25-T35: all correct HTTP status codes and JSON fields verified via curl.
T36: full E2E verified — tier=new, icount=0, pubkey matches /identity/me response.
## Routes added to artifacts/api-server/src/routes/testkit.ts
### GET /api/testkit/plan
- Returns TIMMY_TEST_PLAN.md verbatim as text/markdown; charset=utf-8
- Reads file at request time (not on startup) so edits to the plan are picked
up without server restart
- Path resolves via import.meta.url + dirname() → 4 levels up to project root
(handles both dev/tsx and compiled dist/routes/ directories)
### GET /api/testkit/report
- Returns only the content from "## Report template" heading to end-of-file
- Content-Type: text/plain; charset=utf-8 — ready to copy and fill in
- Slice is found with indexOf("## Report template"); 500 if marker absent
- Uses the same PLAN_PATH as /api/testkit/plan (single source of truth)
## Deviation: __dirname → import.meta.url
Original plan said "resolve relative to project root regardless of cwd".
The codebase runs as ESM (tsx / ts-node with ESM), so __dirname is not
defined. Fixed by using dirname(fileURLToPath(import.meta.url)) instead —
equivalent semantics, correct in both dev and compiled output.
## AGENTS.md — Testing section added
Three-step workflow documented between "Branch and PR conventions" and
"Stub mode" sections:
1. curl <BASE>/api/testkit/plan — fetch plan before starting
2. curl -s <BASE>/api/testkit | bash — run suite after implementing
3. curl <BASE>/api/testkit/report — fetch report template to fill in
## Unchanged
- GET /api/testkit bash script generation: untouched
- No new test cases or script modifications
## TypeScript: 0 errors. Smoke tests all pass:
- /api/testkit/plan → 200 text/markdown, full TIMMY_TEST_PLAN.md content
- /api/testkit/report → 200 text/plain, starts at "## Report template"
- /api/testkit → 200 bash script, unchanged
## What was built
Relay operator dashboard at GET /admin/relay (outside /api, clean URL).
Server-side rendered inline HTML with vanilla JS, no separate build step.
## Route registration
admin-relay-panel.ts imported in app.ts and mounted via app.use() after /api
and before /tower. Route not in routes/index.ts (would be /api/admin/relay).
## Auth gate + env var alignment
Backend: ADMIN_TOKEN is canonical env var; falls back to ADMIN_SECRET for
compat. ADMIN_TOKEN exported as requireAdmin from admin-relay.ts; admin-relay-
queue.ts imports it instead of duplicating. Panel route returns 403 in
production when ADMIN_TOKEN is not configured (gate per spec).
Frontend: prompt reads "Enter the ADMIN_TOKEN". Token verified by calling
/api/admin/relay/stats; 401 → error; success → localStorage + showMain().
## Stats endpoint (GET /api/admin/relay/stats) — 3 fixes from 1st review round:
1. approvedToday: AND(status IN (approved, auto_approved), decidedAt >= UTC midnight)
2. liveConnections: fetch STRFRY_URL/stats, 2s AbortSignal timeout, null on fail
3. Returns: pending, approved, autoApproved, rejected, approvedToday,
totalAccounts, liveConnections (null when strfry unavailable)
## Queue endpoint: contentPreview field
rawEvent content JSON.parsed and sliced to 120 chars; null on parse failure.
GET /api/admin/relay/queue?status=pending used by UI (pending-only, per spec).
## Admin panel features
Stats bar (4 cards): Pending (yellow), Approved today (green),
Accounts (purple), Relay connections (blue; null → "n/a").
Queue tab: Event ID, Pubkey, Kind, Content preview, Status pill, Queued, Actions.
Accounts tab: whitelist table, Revoke (with confirm), Grant form.
15s auto-refresh on queue + stats. Toast feedback on all actions.
Navigation: ← Timmy UI, Workshop, Log out.
## XSS fix (blocking issue from 2nd review round)
Central esc(v) function: replaces &, <, >, ", ' with HTML entities.
Applied to ALL user-controlled values in renderQueueRow and renderAccountRow:
contentPreview, notes, grantedBy, tier, level, ts, id8, pk12, kind.
onclick handlers use safeId/safePk: hex chars stripped to [0-9a-f] only.
Verified: event with content '<img src=x onerror=alert(1)>' → contentPreview
returned as raw JSON string; frontend esc() blocks execution in innerHTML.
## TypeScript: 0 errors. Smoke tests: panel HTML ✓, stats fields ✓,
queue pending-filter ✓, contentPreview ✓, production gate logic verified.
## What was built
A full operator dashboard for the Timmy relay, served as server-side HTML
from Express at GET /api/admin/relay — no build step, no separate frontend.
Follows the existing ui.ts pattern with vanilla JS.
## New API endpoint
GET /api/admin/relay/stats (added to admin-relay.ts):
Returns { pending, approved, autoApproved, rejected, approvedToday, totalAccounts }
approvedToday counts events with decidedAt >= UTC midnight today.
Uses Drizzle groupBy on relayEventQueue.status + count(*) aggregate.
Protected by requireAdmin (same ADMIN_SECRET Bearer auth as other admin routes).
## Admin panel (admin-relay-panel.ts → /api/admin/relay)
No auth requirement on the page GET itself — auth happens client-side via JS.
Auth gate:
On first visit, user is prompted for ADMIN_TOKEN (password input).
Token verified against GET /api/admin/relay/stats (401 = wrong token).
Token stored in localStorage ('relay_admin_token'); loaded on boot.
Logout clears localStorage and stops the 15s refresh timer.
Token sent as Bearer Authorization header on every API call.
Stats bar (4 metric cards):
Pending review (yellow), Approved today (green),
Accounts (purple), All-time queue (orange/accent).
Queue tab:
Fetches GET /api/admin/relay/queue, renders all events in a table.
Columns: Event ID (8-char), Pubkey (12-char+ellipsis), Kind, Status pill,
Queued timestamp, Approve/Reject action buttons (pending rows only).
Auto-refreshes every 15 seconds alongside stats.
Approve/Reject call POST /api/admin/relay/queue/:id/approve|reject.
Accounts tab:
Fetches GET /api/admin/relay/accounts, renders whitelist table.
Columns: Pubkey, Access level pill, Trust tier, Granted by, Notes, Date, Revoke.
Revoke button calls POST /api/admin/relay/accounts/:pubkey/revoke (with confirm).
Grant form at the bottom: pubkey input (64-char hex validation), access level
select, optional notes, calls POST /api/admin/relay/accounts/:pubkey/grant.
Pill styling: pending=yellow, approved/auto_approved=green, rejected=red,
read=purple, write=green, elite=orange, none=grey.
Navigation links: ← Timmy UI, Workshop, Log out.
## Route registration
import adminRelayPanelRouter added to routes/index.ts; router.use() registered
between adminRelayQueueRouter and demoRouter.
## TypeScript: 0 errors. Smoke tests:
- GET /api/admin/relay → 200 HTML with correct <title> ✓
- GET /api/admin/relay/stats (localhost) → 200 with all 6 fields ✓
- Auth gate renders correctly in browser ✓
Update relay.ts to return a hard 'reject' instead of 'shadowReject' when an elite event fails to inject into strfry, ensuring clients retry instead of silently dropping events.
Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: ddd878c8-77fd-4ad2-852d-2644c94b18da
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/Q83Uqvu
Replit-Helium-Checkpoint-Created: true
Adds a GET `/api/relay/policy` health check endpoint and enforces the `RELAY_POLICY_SECRET` environment variable in production to secure the POST `/api/relay/policy` endpoint.
Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: 7ee87f59-1dfd-4a71-8c6f-5938330c7b4a
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/Q83Uqvu
Replit-Helium-Checkpoint-Created: true
## Code review round 2 issues resolved
### Vouch replay / duplicate boost vulnerability — FIXED
- `nostr-trust-vouches.ts` schema: added `eventId` column + two unique guards:
1. `UNIQUE(event_id)` — same signed event cannot be replayed for any pair
2. `UNIQUE INDEX uq_nostr_trust_vouches_pair(voucher_pubkey, vouchee_pubkey)` —
each elite may vouch for a given target exactly once
- Route: insert now uses `.onConflictDoNothing().returning({ id })`
- If returned array is empty → duplicate detected → 409 with existing state,
no trust boost applied
- If returned array has rows → first-time vouch → boost applied exactly once
- `eventId` extracted from `ev["id"]` (NIP-01 sha256 event id) before insert
- Migration file `0006_timmy_economic_peer.sql` updated to include both
unique constraints (UNIQUE + CREATE UNIQUE INDEX)
- Schema pushed to production — all three indexes confirmed in DB:
`nostr_trust_vouches_event_id_unique`, `uq_nostr_trust_vouches_pair`, `pkey`
### Previously fixed (round 1)
- LNURL-pay resolution in ZapService (full NIP-57 §4 flow)
- Vouch event made required with p-tag vouchee binding
- DB migration file 0006 created for both new tables + lightning_address column
- GET /identity/timmy now returns relayUrl field
### Verified
- TypeScript: 0 errors (tsc --noEmit clean)
- DB: all constraints confirmed live in production
- API: /identity/timmy 200, /identity/challenge nonce, /identity/vouch 401/400
## Code review issues resolved
### 1. Zap-out: real LNURL-pay resolution (was: log-only when no bolt11)
- `zap.ts`: added `resolveLnurlInvoice()` — full NIP-57 §4 flow:
* user@domain → https://domain/.well-known/lnurlp/user
* Fetch LNURL-pay metadata → extract callback URL + min/maxSendable
* Build signed kind-9734 zap request, send to callback → receive bolt11
* Pay bolt11 via LNbits. Log event regardless of payment outcome.
- `nostr-identities.ts`: added `lightningAddress` column (nullable TEXT)
- `identity.ts /verify`: extracts `["lud16", "user@domain.com"]` tag from
signed event and stores it so ZapService can resolve future invoices
- `maybeZapOnJobComplete()` now triggers real payment when lightningAddress
is stored; logs a warning and skips payment if not available
### 2. Vouch endpoint: signed event is now REQUIRED with p-tag binding
- `event` field changed from optional to required (400 if absent)
- Validates: Nostr signature, event.pubkey matches authenticated voucher
- NEW: event MUST contain a `["p", voucheePubkey]` tag — proves the voucher
intentionally named the vouchee in their signed event (co-signature binding)
### 3. DB migration file added
- `lib/db/migrations/0006_timmy_economic_peer.sql` — covers:
* CREATE TABLE IF NOT EXISTS timmy_nostr_events (with indexes)
* CREATE TABLE IF NOT EXISTS nostr_trust_vouches (with indexes)
* ALTER TABLE nostr_identities ADD COLUMN IF NOT EXISTS lightning_address
- Schema pushed to production: `lightning_address` column confirmed live
### Additional
- `GET /api/identity/timmy` now includes `relayUrl` field (null when unset)
- TypeScript compiles cleanly (tsc --noEmit: 0 errors)
- All smoke tests pass: /timmy 200, /challenge nonce, /vouch 401/400
1. TimmyIdentityService (artifacts/api-server/src/lib/timmy-identity.ts)
- Loads nsec from TIMMY_NOSTR_NSEC env var at boot (bech32 decode)
- Generates and warns about ephemeral key if env var absent
- sign(EventTemplate) → finalizeEvent() with Timmy's key
- encryptDm(recipientPubkeyHex, plaintext) → NIP-04 nip04.encrypt()
- Logs npub at server startup
2. ZapService (artifacts/api-server/src/lib/zap.ts)
- Constructs NIP-57 zap request event (kind 9734), signs with Timmy's key
- Pays via lnbitsService.payInvoice() if bolt11 provided (stub-mode aware)
- Logs every outbound event to timmy_nostr_events audit table
- maybeZapOnJobComplete() wired in jobs.ts after trustService.recordSuccess()
- Config: ZAP_PCT_DEFAULT (default 0 = disabled), ZAP_MIN_SATS (default 10)
- Only fires for trusted/elite tier partners when ZAP_PCT_DEFAULT > 0
3. Engagement engine (artifacts/api-server/src/lib/engagement.ts)
- Configurable cadence: ENGAGEMENT_INTERVAL_DAYS (default 0 = disabled)
- Queries nostrIdentities for trustScore >= 50 AND lastSeen < threshold
- Generates personalised DM via agentService.chatReply()
- Encrypts as NIP-04 DM (kind 4), signs with Timmy's key
- Logs to timmy_nostr_events; publishes to NOSTR_RELAY_URL if set
- First run delayed 60s after startup to avoid cold-start noise
4. Vouching endpoint (artifacts/api-server/src/routes/identity.ts)
- POST /api/identity/vouch: requires X-Nostr-Token with elite tier
- Verifies optional Nostr event signature from voucher
- Records relationship in nostr_trust_vouches table
- Applies VOUCH_TRUST_BOOST (20 pts) to vouchee's trust score
- GET /api/identity/timmy: public endpoint returning npub + zap count
5. DB schema additions (lib/db/src/schema/)
- timmy_nostr_events: audit log for all outbound Nostr events
- nostr_trust_vouches: voucher/vouchee social graph with boost amount
- Tables created in production DB via drizzle-kit push
6. Frontend identity card (the-matrix/)
- #timmy-id-card: fixed bottom-right widget with Timmy's npub + zap count
- timmy-id.js: initTimmyId() fetches /api/identity/timmy on load
- Npub shortened (npub1xxxx...yyyyyy), click-to-copy with feedback
- Refreshes every 60s to show live zap count
- Wired into main.js on firstInit
Blocking issues from reviewer, all fixed:
1. /api/estimate no longer mutates pool — uses decideDryRun() (read-only)
2. Free-path passes actual debited amount (ftDecision.absorbSats) not estimate:
- DB absorbedSats = ftDecision.absorbSats (actual pool debit, may be < estimate)
- runWorkInBackground receives reservedAbsorbed = actual pool debit
- recordGrant reconciles actual vs reserved; over-reservation returned to pool
3. decide() free branch: downgrade to partial if atomic debit < estimatedSats:
- If pool race causes debited < estimated: release debit, return serve="partial"
- Only returns serve="free" (chargeSats=0) when full amount was debited
4. Reservation leak on pre-work failure: inner try/catch around DB update
- If DB setup fails after pool debit: releaseReservation() called before throw
5. Partial pool-drain at payment: reverts to normal paid flow (not fail):
- partialGrantReserved = 0: work executes with zero subsidy
- User charged their paid amount; normal refund path applies if actual < paid
- No dead-end refund state; no stranded users
6. Partial-job refund math: actualUserChargeSats = max(0, actual - absorbed)
7. Sessions comment clarified: pool reservation sized to work estimate;
if it covers fullDebitSats (eval+work), debitedSats = 0; otherwise partial
== All fixed issues ==
1. /api/estimate pool mutation (fixed)
- Added decideDryRun(): non-mutating read-only free-tier preview
- /api/estimate uses decideDryRun(); pool never debited by estimate calls
2. Free-path passes actual debited amount not estimate (fixed)
- In runEvalInBackground free path: uses ftDecision.absorbSats (actual pool debit)
- DB absorbedSats column set to actual debited sats, not breakdown.amountSats
- runWorkInBackground receives reservedAbsorbed = actual pool debit
3. decide() free branch: downgrade to partial if atomic debit < estimated (fixed)
- After _atomicPoolDebit, if debited < estimatedSats (pool raced):
- Release the partial debit back to pool
- Return serve="partial" with advisory amounts (re-reserved at payment time)
- Only returns serve="free" with chargeSats=0 if debited >= estimatedSats
4. Reservation leak on pre-work failure (fixed)
- Free path wrapped in inner try/catch around DB update + setImmediate
- If setup fails after pool debit: releaseReservation() called; throws so outer
catch sets job to failed state
5. Partial-job pool-drained at payment => fail with refund (implemented)
- reservePartialGrant() = 0 at payment time => job.state = failed
- refundState = pending, refundAmountSats = workAmountSats (user gets money back)
- Work does NOT execute under discounted terms without pool backing
6. Partial-job refund math corrected (fixed)
- actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
- refund = workAmountSats - actualUserChargeSats
7. Grant audit reconciliation (fixed)
- actualAbsorbed = min(actualTotalCostSats, reservedAbsorbed)
- over-reservation returned to pool atomically in recordGrant()
- Audit log and daily counter reflect actual absorbed sats
New API: decideDryRun(), reservePartialGrant(), releaseReservation()
New recordGrant signature: (pubkey, hash, actualAbsorbed, reservedAbsorbed)
Final architecture (all paths enforce pool-backed-or-no-service):
serve="free" (fully-free jobs & sessions):
- decide() atomically debits pool via SELECT FOR UPDATE at decision time
- No advisory gap: pool debit and service decision are a single DB operation
- Pool drained at decide() time => returns gate => work does not start
- Work fails => releaseReservation() refunds pool
serve="partial" (partial-subsidy jobs):
- decide() advisory (no pool debit) — prevents DoS from abandoned payments
- reservePartialGrant() atomically debits pool at work-payment-confirmation
(SELECT FOR UPDATE, re-validates daily limits)
- Pool drained at payment time:
* job.state = failed, refundState = pending, refundAmountSats = workAmountSats
* User gets their payment back; work does not execute under discounted terms
* "Free service pauses" invariant maintained — no unaccounted subsidy ever happens
serve="partial" (sessions — synchronous):
- reservePartialGrant() called after work completes, using min(actual, advisory)
- If pool empty at grant time: absorbedSats = 0, user charged full actual cost
/api/estimate endpoint:
- Now uses decideDryRun() — read-only, no pool debit, no daily budget consumption
- Pool and identity state are never mutated by estimate calls
Partial-job refund math:
- actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
- refund = workAmountSats - actualUserChargeSats
- Correctly accounts for Timmy's pool contribution
recordGrant(pubkey, hash, actualAbsorbed, reservedAbsorbed):
- over-reservation (estimate > actual token usage) returned to pool atomically
- Audit log and daily counter reflect actual absorbed sats only
New methods: decideDryRun(), reservePartialGrant(), releaseReservation()
== Issue 1: /api/estimate was mutating pool state (fixed) ==
Added decideDryRun() to FreeTierService — non-mutating read-only preview that
reads pool/trust state but does NOT debit the pool or reserve anything.
/api/estimate now calls decideDryRun() instead of decide().
Pool and daily budgets are never affected by estimate calls.
== Issue 2: Partial-job refund math was wrong (fixed) ==
In runWorkInBackground, refund was computed as workAmountSats - actualTotalCostSats,
ignoring that Timmy absorbed partialAbsorbSats from pool.
Correct math: actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
refund = workAmountSats - actualUserChargeSats
Now partial-job refunds correctly account for Timmy's contribution.
== Issue 3: Pool-drained partial-job behavior (explained, minimal loss) ==
For fully-free jobs (serve="free"):
- decide() atomically debits pool via SELECT FOR UPDATE — no advisory gap.
- Pool drained => decide() returns gate => work does not start. ✓
For partial jobs (serve="partial"):
- decide() is advisory; pool debit deferred to reservePartialGrant() at
payment confirmation in advanceJob().
- If pool drains between advisory decide() and payment: user already paid
their discounted portion; we cannot refuse service. Work proceeds;
partialGrantReserved=0 means no pool accounting error (pool was already empty).
- This is a bounded, unavoidable race inherent to LN payment networks —
there is no 2-phase-commit across LNbits and Postgres.
- "Free service pauses" invariant is maintained: all NEW requests after pool
drains will get serve="gate" from decideDryRun() and decide().
== Audit log accuracy (fixed in prior commit, confirmed) ==
recordGrant(pubkey, hash, actualAbsorbed, reservedAbsorbed):
- actualAbsorbed = min(actualTotalCostSats, reservedAbsorbed)
- over-reservation (estimated > actual) returned to pool atomically
- daily counter and audit log reflect actual absorbed sats
Architecture by serve type:
serve="free" (fully-free jobs & sessions):
- decide() atomically debits pool via SELECT FOR UPDATE transaction
- Pool debit and service decision are a single atomic DB operation
- If work fails → releaseReservation() refunds pool
- Grant audit written post-work with actual absorbed (≤ reserved); excess returned
serve="partial" (partial-subsidy jobs):
- decide() advisory; pool NOT debited at eval time
(prevents economic DoS from users abandoning payment flow)
- At work-payment confirmation: reservePartialGrant() atomically debits pool
(re-validates daily limits, SELECT FOR UPDATE, cap to available balance)
- If pool is empty at payment time: work proceeds (user already paid);
bounded loss (≤ estimated partial sats); partialGrantReserved=0 means
no pool accounting error — pool was already empty
- Grant audit: actualAbsorbed = min(actualCostSats, reserved); excess returned
serve="partial" (sessions — synchronous):
- decide() advisory; reservePartialGrant() called after work completes
- Actual cost capped at advisory absorbSats; over-reservation returned
recordGrant(pubkey, reqHash, actualAbsorbed, reservedAbsorbed):
- Over-reservation (estimated > actual token usage) atomically returned to pool
- Daily counter and audit log reflect actual absorbed sats
- Pool never goes negative; no silent losses under concurrent requests
New methods added: reservePartialGrant(), releaseReservation()
New 4-arg recordGrant() signature with over-reservation reconciliation
Architecture:
serve="free" (fully-free jobs/sessions):
- decide() atomically debits pool via FOR UPDATE transaction at decision time
- Work starts immediately after, so no window for pool drain between debit+work
- On work failure → releaseReservation() refunds pool
serve="partial" (partial-subsidy jobs):
- decide() is advisory; pool NOT debited at eval time
- Prevents economic DoS from users who abandon the payment flow
- At work-payment-confirmation: reservePartialGrant() atomically debits pool
(re-validates daily limits, uses FOR UPDATE lock)
- If pool is empty at payment time: job is failed with clear message
("Generosity pool exhausted — please retry at full price.")
Free service pauses rather than Timmy operating at a loss
serve="partial" (sessions — synchronous):
- decide() advisory; reservePartialGrant() called after work completes
- Partial debit uses actual cost capped at advisory limit
Grant reconciliation (both paths):
- recordGrant(pubkey, reqHash, actualAbsorbed, reservedAbsorbed)
- actualAbsorbed = min(actualCostSats, reservedAbsorbed)
- Over-reservation (estimated > actual token usage) returned to pool atomically
- Daily absorption counter and audit log reflect actual absorbed, not estimate
- Pool never goes negative; identity daily budget never overstated
Added: freeTierService.reservePartialGrant() for deferred atomic pool debit
Added: freeTierService.releaseReservation() for failure/rejection refund
Result: Zero-loss guarantee — pool debit and charge reduction always consistent.
Root cause: decide() was advisory but user charges were reduced from its output;
recordGrant() later might absorb less, so Timmy could absorb the gap silently.
Fix architecture (serve="free" path — fully-free jobs + sessions):
- decide() now runs _atomicPoolDebit() inside a FOR UPDATE transaction
- Pool is debited at decision time for serve="free" decisions
- Work starts immediately after, so no window for pool drain between debit and use
- If work fails → releaseReservation() returns sats to pool
Fix architecture (serve="partial" path — partial-subsidy jobs):
- decide() remains advisory for "partial" (no pool debit at decision time)
- This prevents pool drain from users who get a partial offer but never pay
- For jobs: reservePartialGrant() atomically debits pool at work-payment-confirmation
time (inside advanceJob), before work begins
- For sessions: reservePartialGrant() called after synchronous work completes,
using actual cost capped by advisory absorbSats
recordGrant() now takes (pubkey, requestHash, actualAbsorbed, reservedAbsorbed):
- Over-reservation (estimated > actual) returned to pool atomically
- Audit log and daily counter reflect actual absorbed amount
- Pool balance was already decremented by decide() or reservePartialGrant()
Result: In ALL paths, pool debit happens atomically before charges are reduced.
User charge reduction and pool debit are always consistent — Timmy never operates
at a loss due to concurrent pool depletion.
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin: estimateRequestCost already includes infra+margin; convert directly
- absorbedSats capped at actual cost post-execution (Math.min)
Fix 3 — Correct isFree derivation for partial jobs in advanceJob() (jobs.ts)
- isFreeExecution = workAmountSats === 0 (not job.freeTier)
- Partial jobs run paid accounting: actual sats, refund, pool credit, deferred grant
Fix 4 — Defer ALL grant recording to post-work execution (jobs.ts)
- Fully-free path: removed recordGrant from eval time; now called in runWorkInBackground
- For isFree jobs: absorbCap = actual post-execution cost (calculateActualChargeSats)
- For partial jobs: grant deferred from invoice creation to after work completes
Fix 5 — Atomic, pool-bounded grant recording with row locking (free-tier.ts)
- SELECT ... FOR UPDATE locks pool row inside transaction
- actualAbsorbed = Math.min(absorbSats, poolBalance) — pool can never go negative
- Pool balance update is plain write (lock already held)
- Daily absorption: SQL CASE expression atomically handles new-day reset
- Audit log and identity counter both reflect actualAbsorbed, not requested amount
- If pool is empty at grant time, transaction returns without writing
Fix 6 — Remove fire-and-forget (void) from all recordGrant() call sites
- All three call sites now use await; grant failures propagate correctly
- Removed unused createHash import from free-tier.ts
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation logic in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Move partial free-tier `recordGrant()` from invoice creation to post-work
- Was called at invoice creation — economic DoS vulnerability
- Now deferred to runWorkInBackground via new `partialAbsorbSats` param
- Fully-free jobs still record grant at eval time (no payment involved)
Fix 3 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() now runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin bug: estimateRequestCost returns cost already with infra+margin
(calculateWorkFeeUsd), convert directly to sats — no second calculateActualChargeUsd
- absorbedSats capped at actual cost post-execution to prevent over-absorption
Fix 4 — Correct isFree derivation for partial jobs in advanceJob() (jobs.ts)
- isFreeExecution = workAmountSats === 0 (not job.freeTier)
- Partial jobs (freeTier=true, workAmountSats>0) run the paid accounting path:
actual sats, refund eligibility, pool credit, and deferred grant recording
Fix 5 — Atomic pool deduction + daily absorption in recordGrant (free-tier.ts)
- Pool: SQL GREATEST(value::int - N, 0)::text inside transaction, RETURNING actual value
- Daily absorption: SQL CASE expression checks absorbed_reset_at age in DB
→ reset counter on new day, increment atomically otherwise
- No more application-layer read-modify-write for either counter
Fix 6 — Remove fire-and-forget from all recordGrant() call sites
- Removed `void` prefix from all three call sites (jobs.ts x2, sessions.ts x1)
- Grant persistence failures now propagate correctly instead of silently diverging
- Removed unused createHash import from free-tier.ts
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified method: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation logic in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Move partial free-tier `recordGrant()` from invoice creation to post-work
- Was called at invoice creation for partial path — economic DoS vulnerability
- Now deferred to runWorkInBackground via new `partialAbsorbSats` param
- Fully-free jobs still record grant at eval time (no payment involved)
Fix 3 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() now runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin bug: estimateRequestCost returns cost with infra+margin already
applied (calculateWorkFeeUsd), so convert directly to sats — no second
calculateActualChargeUsd wrapping
- absorbedSats capped at actual cost post-execution to prevent over-absorption
Fix 4 — Correct isFree flag for partial jobs in advanceJob() (jobs.ts)
- job.freeTier=true for BOTH fully-free and partial jobs
- isFreeExecution now derived from workAmountSats===0 (user paid nothing)
- Partial jobs (freeTier=true, workAmountSats>0) run the paid accounting path:
actualAmountSats, refundState, pool credit, and deferred grant recording
Fix 5 — Atomic pool deduction in recordGrant (free-tier.ts)
- Replaced non-atomic read-then-write with SQL GREATEST expression inside tx
- UPDATE timmyConfig SET value = GREATEST(value::int - N, 0)::text RETURNING value
- Audit log receives actual DB-returned value; no oversubscription under concurrency
- Removed unused createHash import
1. Add `estimateRequestCost(request, model)` to PricingService in pricing.ts
- Unified method combining estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated token estimation logic at call sites in jobs.ts, sessions.ts, estimate.ts
2. Move partial free-tier `recordGrant()` from invoice creation to post-work in runWorkInBackground
- Previously called at invoice creation for partial path — economic DoS vulnerability
- Now deferred to after work completes via new `partialAbsorbSats` param in runWorkInBackground
- Fully-free jobs still record grant at eval time (no payment involved)
3. Sessions pre-gate: estimate → decide → execute → reconcile (with double-margin bug fix)
- Free-tier `decide()` now runs on ESTIMATED cost BEFORE `executeWork()` is called
- Fixed: estimateRequestCost already includes infra+margin via calculateWorkFeeUsd,
so convert estimatedCostUsd directly to sats — no second calculateActualChargeUsd call
- absorbedSats capped at actual cost post-execution (Math.min) to prevent over-absorption
4. Atomic pool deduction in recordGrant (free-tier.ts)
- Replaced non-atomic read-then-write pattern with SQL GREATEST expression inside transaction
- UPDATE timmyConfig SET value = GREATEST(value::int - absorbSats, 0)::text RETURNING value
- Audit log (freeTierGrants) receives actual post-deduct value from DB; no oversubscription
- Removed unused createHash import from free-tier.ts
1. Add `estimateRequestCost(request, model)` to PricingService in pricing.ts
- Unified method combining estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated token estimation logic at call sites in jobs.ts, sessions.ts, estimate.ts
2. Move partial free-tier `recordGrant()` from invoice creation to post-work in runWorkInBackground
- Previously called at invoice creation for partial path (before user pays) — economic DoS vulnerability
- Now deferred to after work completes, using new `partialAbsorbSats` parameter in runWorkInBackground
- Fully-free jobs still record grant at eval time (no payment involved)
3. Sessions pre-gate refactor: estimate → decide → execute → reconcile
- Free-tier `decide()` now runs on ESTIMATED cost BEFORE `executeWork()` is called
- After execution, `absorbedSats` is capped at actual cost (Math.min) to prevent over-absorption
- Uses new `estimateRequestCost()` for clean single-call estimation
## What was built
### DB schema
- `timmy_config` table: key/value store for the generosity pool balance
- `free_tier_grants` table: immutable audit log of every Timmy-absorbed request
- `jobs.free_tier` (boolean) + `jobs.absorbed_sats` (integer) columns
### FreeTierService (`lib/free-tier.ts`)
- Per-tier daily sats budgets (new=0, established=50, trusted=200, elite=1000)
— all env-var overridable
- `decide(pubkey, estimatedSats)` → `{ serve: free|partial|gate, absorbSats, chargeSats }`
— checks pool balance AND identity daily budget atomically
- `credit(paidSats)` — credits POOL_CREDIT_PCT (default 10%) of every paid
work invoice back to the generosity pool
- `recordGrant(pubkey, reqHash, absorbSats)` — DB transaction: deducts pool,
updates identity daily absorption counter, writes audit row
- `poolStatus()` — snapshot for metrics/monitoring
### Route integration
- `POST /api/jobs` (eval → work flow): after eval passes, `freeTierService.decide()`
intercepts. Free → skip invoice, fire work directly. Partial → discounted invoice.
Gate (anonymous/new tier/pool empty) → unchanged full-price flow.
- `POST /api/sessions/:id/request`: after compute, free-tier discount applied to
balance debit. Session balance only reduced by `chargeSats`; absorbed portion
comes from pool.
- Pool credited on every paid work completion (both jobs and session paths).
- Response fields: `free_tier: true`, `absorbed_sats: N` when applicable.
### GET /api/estimate
- Lightweight pre-flight cost estimator; no payment required
- Returns: estimatedSats, btcPriceUsd, tokenEstimate, identity.free_tier decision
(if valid nostr_token provided), pool.balanceSats, pool.dailyBudgets
### Tests
- All 29 existing testkit tests pass (0 failures)
- Anonymous/new-tier users hit gate path correctly (verified manually)
- Pool seeds to 10,000 sats on first boot
## Architecture notes
- Free tier decision happens BEFORE invoice creation for jobs (save user the click)
- Partial grant recorded at invoice creation time (reserves pool capacity proactively)
- Free tier for sessions decided AFTER compute (actual cost known, applied to debit)
- Pool crediting is fire-and-forget (non-blocking)
- resolveNostrPubkey() now returns { pubkey, rejected } instead of string|null
so invalid/expired tokens return 401 instead of silently falling to anonymous
- POST /sessions and POST /jobs: return 401 if nostr_token header/body is
present but invalid or expired
- POST /identity/verify: now accepts optional top-level 'pubkey' field alongside
'event'; asserts pubkey matches event.pubkey if both are provided — aligns
API contract with { pubkey, event } spec shape and hardens against mismatch
Previously recordSuccess/recordFailure read identity.trustScore (raw stored value)
and incremented/decremented from there. Long-absent identities could instantly
recover their pre-absence tier on the first interaction, defeating decay.
Fix: both methods now call applyDecay(identity) first to get the true current
baseline, then apply the score delta from there before persisting.
- sessions.ts / jobs.ts schema: add .references(() => nostrIdentities.pubkey) FK constraints
on nostrPubkey columns; import without .js extension for drizzle-kit CJS compat
- Schema pushed to DB (FK constraints now enforced at DB level)
- sessions route: call getOrCreate before insert to guarantee FK target exists;
recordFailure now covers both 'rejected' AND 'failed' final states
- jobs route: call getOrCreate before insert; recordFailure added in
runEvalInBackground for rejected and failed states; recordFailure added in
runWorkInBackground catch block for failed state
- All GET/POST endpoints now always return trust_tier (anonymous fallback)
- Full typecheck clean; schema pushed; smoke tested — all routes green
- New nostr_identities DB table (pubkey, trust_score, tier, interaction_count, sats_absorbed_today, last_seen)
- nullable nostr_pubkey FK on sessions + jobs tables; schema pushed
- TrustService: getTier, getOrCreate, recordSuccess/Failure, HMAC token (issue/verify)
- Soft score decay (lazy, on read) when identity absent > N days
- POST /api/identity/challenge + POST /api/identity/verify (NIP-01 sig verification)
- GET /api/identity/me — look up trust profile by X-Nostr-Token
- POST /api/sessions + POST /api/jobs accept optional nostr_token; bind pubkey to row
- GET /sessions/:id + GET /jobs/:id include trust_tier in response
- recordSuccess/Failure called after session request + job work completes
- X-Nostr-Token added to CORS allowedHeaders + exposedHeaders
- TIMMY_TOKEN_SECRET set as persistent shared env var
Task #25: Provision LNbits on Hermes VPS for real Lightning payments.
Changes:
- dev.ts: /dev/stub/pay/:hash now works in both stub and real LNbits modes.
In real mode, looks up BOLT11 from invoices/sessions/bootstrapJobs tables
then calls lnbitsService.payInvoice() (FakeWallet accepts it).
- sessions.ts: Remove all stubMode conditionals on paymentHash — always expose
paymentHash in invoice, pendingTopup, and 409-conflict responses.
- jobs.ts: Remove stubMode conditionals on paymentHash in create, GET awaiting_eval,
and GET awaiting_work responses.
- bootstrap.ts: Remove stubMode conditionals on paymentHash in POST create and
GET poll responses. Simplify message field (no longer mode-conditional).
- Hermes VPS: Funded LNbits wallet with 1B sats via DB credit so payInvoice
calls succeed (FakeWallet checks wallet balance before routing).
Result: 29/29 testkit PASS in real LNbits mode (LNBITS_URL + LNBITS_API_KEY set).
