KodaBuild Progress

Spec: v1.0

Domain: koda.systems

Node.js: v25.9.0

PostgreSQL: 16

MacBook Air · Apple M3

24 GB · 4 Performance and 4 Efficiency

Koda Core 2.100.1

Console 1.39.1

VS Code Bridge 0.3.0

Dashboard Gen 1.11.0

Deploy Watch 1.1.2

koda-dashboard 1.3.2

DET22 1.10.3

User Mgmt 1.9.0

keysvc 0.1.0

network-diagram-skill 0.2.1

✓ Node.js via NVM (v24.14.0)

✓ PostgreSQL 16 (Homebrew service)

✓ PostgREST (launchd, port 3000)

✓ Docker Desktop

✓ signal-cli REST API Docker (json-rpc mode, port 8080, v0.98+ required for quote/mention fields)

✓ Bridge server (launchd, port 3033)

✓ Playwright MCP (launchd, port 8931)

✓ Wrangler CLI installed

✓ Wrangler authenticated (wrangler login)

✓ Cloudflare account ID in .env; API token in credential store (cloudflare-wrangler)

✓ Git repo (github.com/cliaz/koda)

✓ SSH deploy key on GitHub

✓ Central env file (scripts/koda-env.sh) for PATH management

✓ PostgreSQL + NVM node in ~/.bashrc PATH

✓ Sleep disabled (sudo pmset -a sleep 0 disksleep 0)

✓ Auto-login enabled

✓ All 17 tables created (users, groups, messages, sessions, tasks, memories, attachments, instructions, skills, deployments, credentials, browser_sessions, email_actions, audit_log, error_log, usage_alert_config, system_config)

✓ koda_core role + grants (renamed from koda_bridge)

✓ koda_agent role + grants

✓ koda_owner role (created with SELECT grants)

✓ RLS enabled on project-scoped tables

✓ koda_agent RLS policies (all 8 tables)

✓ koda_core RLS policies (all tables — full access)

✓ PostgREST JWTs generated

✓ pg_hba.conf trust auth for local sockets

✓ Response caching for identical read-only queries within 60s (in-memory, invalidated on writes)

✓ Signal bot registered (+61460036867)

✓ Device linked as secondary

✓ WebSocket receiver (json-rpc mode)

✓ @mention trigger detection in groups

✓ Piecemeal batching in DM

✓ Read receipts

✓ Markdown stripping from Claude responses

✓ Chunk numbering [1/N] format

— Message edit handling (out of scope)

✓ Unknown UUID silent ignore (logged, no response)

✓ DM batching uses timer (1500ms) not explicit @mention trigger — simpler, functionally equivalent (spec deviation accepted)

✓ Inbound message logging to DB

✓ Outbound message logging (with Signal send timestamp as message_id)

✓ Quote/reply context resolution (DB lookup → content fallback → Signal text)

✓ quoted_message_id stored on inbound messages that quote/reply

✓ Message chunking at 1500 chars

✓ Working... notification before Claude invocation

✓ Concurrency control with FIFO queue (queued requests notified)

✓ Global rate limit (RATE_LIMIT_GLOBAL)

✓ Owner exempt from per-user rate limit

✓ UUID-based user lookup

✓ Owner/Admin/User roles

✓ Permissions table + capability grants

✓ hasPermission / hasRole functions

✓ Slash command aliases (/adduser, /removeuser, /setrole, /listusers, /grant, /revoke)

✓ Full capability enforcement for all 15 grantable capabilities

✓ Capability validation on /user grant (rejects invalid capability names)

✓ Sender capabilities included in Claude Code system prompt

✓ /grants <uuid> command (list grants for a user)

✓ /listusers shows roles and current grants per user

✓ /user add takes phone (generates UUID) — better UX than spec's /adduser <uuid> <role> (spec deviation accepted)

✓ Memory schema (memories table with priority column)

✓ /memory list|add|delete|search commands

✓ Memories injected into system prompt (global + session, priority-sorted, token budget enforced)

✓ Memory token budget enforcement (MEMORY_TOKEN_BUDGET, ~4 chars/token estimate)

✓ /memory clear global sub-command

✓ /memory list includes global memories (queries group_id match + IS NULL)

✓ /memory commands restricted to owner

✓ /instructions set (supports inline text or .md/.txt file attachment)

✓ Content hash to skip recondensation

✓ Condensation via truncation (2000 chars) — replaced Claude subprocess in Round 4

✓ <!-- ALWAYS INCLUDE --> marker support

✓ fs.watch on instructions directory

✓ /instructions clear command

✓ Global vs session scope enforcement (global = owner only, session = set_instructions_session capability)

✓ skills/ directory + index.json

✓ /skills list (also accepts /skill)

✓ /skills show <name>

✓ /skills delete <name> (owner only)

✓ Skills index path in system prompt

✓ Pre/post git checkpoints (self-modify.sh)

✓ Auto-rollback on failure (verify health, revert file + commit)

✓ One-file-per-change rule enforcement (system prompt instructions)

✓ /modify command (owner only, 10 min timeout, auto-approved)

✓ Self-modification skill file + index entry

✓ AES-256-GCM credential encryption

✓ .secrets/credential_key (chmod 600)

✓ .gitignore excludes .env, .secrets/, node_modules/

✓ pg_hba.conf trust auth

✓ File permissions health check on startup

✓ --dangerously-skip-permissions always on — required because bridge is non-interactive (spec deviation accepted)

✓ Credential heuristic detection in plain messages

✓ Message redaction for /cred and /config commands

— Gmail MCP (deferred by user)

◐ SMTP config in .env (vars present, empty values) (Variables present but empty)

— Action item extraction

— /emailsend autoapprove

— Google Calendar MCP (deferred by user)

✓ /cred set (encrypt + store)

✓ /cred get (decrypt + return)

✓ /cred delete

✓ /config set|get|list — .env management via Signal (allowlisted keys, sensitive values encrypted at rest)

✓ Message redaction from log on credential commands

✓ Credential heuristic detection

✓ Uses /cred set|get|delete instead of spec's /addcredential, /removecredential — clearer naming (spec deviation accepted)

✓ Inbound attachment save to disk

✓ Attachment metadata to DB

✓ Directory structure (attachments/, instructions/, skills/, logs/, screenshots/)

✓ upload_files capability enforcement

✓ Outbound file send (detects file paths in Claude output, sends as Signal attachments)

✓ @playwright/mcp installed globally

✓ Chromium binary installed

✓ Launchd plist running (port 8931)

✓ SSE protocol client in bridge (callPlaywrightMCPTool)

✓ Persistent browser profile for claude.ai (.browser-profile/)

✓ Claude.ai login session established

✓ Prompt injection mitigation in system prompt (instructs Claude to ignore web page instructions)

✓ Wrangler installed

✓ Wrangler authenticated

✓ Cloudflare account ID in .env

✓ Cloudflare API token in credential store (domain: cloudflare-wrangler)

✓ Auto-deploy watcher script (deploy-watch.sh + fswatch)

✓ Deploy-watch launchd plist (com.koda.deploy-watch)

✓ koda.systems custom domain + SSL

✓ koda.systems dashboard deployed and live

✓ Dashboard password protected (SHA-256 gate)

✓ install-checklist.md + install-notes.md downloadable from dashboard

✓ Playwright-based scraping of claude.ai/settings/usage (headed mode, persistent profile)

✓ In-memory cache (sessionPct, weeklyPct, reset times)

✓ Activity-aware polling (5 min after invocations, 60 min idle)

✓ Threshold crossing detection (once per crossing)

✓ /usage command suite (plain, refresh, set target, set thresholds, alerts, status)

✓ usage_alert_config DB persistence

✓ Scrape failure handling (logged + alerts owner via Signal)

✓ error_log table + logError function

✓ uncaughtException handler

✓ unhandledRejection handler

✓ Claude Code exit handling (logged + error message to user + owner notification)

○ Approval timeout — REMOVED in v2.96.1 (approval flow was dead code, all plumbing dropped)

✓ unhandledRejection notifies Owner via Signal + logs to error_log

✓ Signal send retry with backoff (3x, exponential)

✓ PostgREST retry with backoff (3x, skips 4xx client errors)

✓ Empty Claude response sends fallback message to user

✓ Signal send failures propagated and logged (signalSend/signalSendGroup return boolean, sendChunked tracks failures)

✓ Normal mode (message -> Claude Code)

○ Auto-approve mode — REMOVED in v2.96.0 (/autoapprove command and backing plumbing dropped; --dangerously-skip-permissions makes it moot)

○ Approval relay — REMOVED in v2.96.0 (was dead code; --dangerously-skip-permissions bypasses all prompts)

○ /autoapprove status sub-command — REMOVED in v2.96.0

✓ /status sub-commands (errors, logs, sessions, users, memories)

✓ VS Code routing via /route vscode (extension + bridge)

✓ Bridge launchd (KeepAlive)

✓ PostgREST launchd

✓ Playwright MCP launchd

✓ Docker restart policy (unless-stopped)

✓ logrotate.conf

✓ prune-logs.sh

✓ Crontab entry for log pruning (daily 3am)

✓ Daily log file rotation (bridge-YYYY-MM-DD.log with symlink)

✓ Graceful shutdown with drain (30s timeout, rejects new messages during drain)

✓ tests/run_tests.js (62 tests passing)

✓ Test coverage (encryption, chunking, rate limiting, JWT, PostgREST, Signal, file structure, RBAC, markdown stripping, outbound file detection, memories, sessions, instructions, message pipeline, skills, audit/error logs)

✓ Test DB (koda_test) separate from production

✓ Test results to JSON file (tests/results.json)

✓ Signal vars

✓ Processing vars (MAX_CONCURRENT_CLAUDE, BATCH_DELAY_MS, MAX_SIGNAL_CHUNK)

✓ PostgREST vars

✓ Cloudflare vars (all set)

✓ Usage monitoring vars

✓ SMTP vars (present, empty)

○ APPROVAL_TIMEOUT_MINUTES — REMOVED in v2.96.1

✓ RATE_LIMIT_GLOBAL

✓ MEMORY_TOKEN_BUDGET

○ AUTO_APPROVE_DEFAULT — REMOVED in v2.96.1

— EMAIL_SEND_AUTOAPPROVE (email deferred)

✓ TEST_DB_NAME, TEST_SIGNAL_GROUP_ID, TEST_OWNER_UUID

✓ Some env var names differ from spec (SIGNAL_PHONE vs SIGNAL_BOT_NUMBER, MAX_SIGNAL_CHUNK vs MESSAGE_SPLIT_LENGTH, etc.) — implementation names are clearer (spec deviation accepted)

✓ Route selection persisted to system_config table (survives restarts)

✓ All env vars documented in .env.example (ACTIVE_ROUTE, MEMORY_TOKEN_BUDGET, RATE_LIMIT_GLOBAL)