tenet-diagnose

name	tenet:diagnose
description	Diagnose tenet project issues by inspecting SQLite state, job history, event logs, and .tenet/ directory structure. Use when: tenet is misbehaving, jobs are stuck, eval keeps failing, MCP server won't start, or you need to understand what happened during an autonomous run. Triggers on: 'tenet diagnose', 'what went wrong', 'why did tenet fail', 'debug tenet', 'tenet health', 'check tenet state'.
allowed-tools	["Bash","Read","Glob","Grep"]

Tenet Diagnose Skill

You are a tenet diagnostic expert. You know tenet's internals: SQLite schema, job lifecycle, MCP server architecture, adapter invocation, and the .tenet/ directory structure.

Quick Start

Run these diagnostic queries to get a full picture:

1. Project structure check

# Verify .tenet directory exists and has expected structure
ls -la .tenet/
ls -la .tenet/.state/

Expected: interview/, spec/, harness/, status/, knowledge/, journal/, steer/, bootstrap/, visuals/, .state/ directories. .state/ should contain tenet.db and optionally config.json.

2. Database health

# Check DB exists and is readable
sqlite3 .tenet/.state/tenet.db "PRAGMA integrity_check"

# Schema version check — verify all expected columns exist
sqlite3 .tenet/.state/tenet.db "PRAGMA table_info(jobs)"

Expected columns: id, type, status, params, agent_name, created_at, started_at, completed_at, last_heartbeat, retry_count, max_retries, parent_job_id, error, output, server_id

3. Job status overview

# Summary counts by type and status
sqlite3 .tenet/.state/tenet.db "SELECT type, status, COUNT(*) FROM jobs GROUP BY type, status ORDER BY type, status"

# Any stuck 'running' jobs?
sqlite3 .tenet/.state/tenet.db "SELECT id, type, substr(json_extract(params, '$.name'), 1, 50) as name, datetime(started_at/1000, 'unixepoch', 'localtime') as started, datetime(last_heartbeat/1000, 'unixepoch', 'localtime') as heartbeat FROM jobs WHERE status='running'"

4. Failed jobs analysis

# Show all failures with error messages
sqlite3 .tenet/.state/tenet.db "SELECT substr(json_extract(params, '$.name'), 1, 50) as name, type, error, datetime(completed_at/1000, 'unixepoch', 'localtime') as failed_at, (completed_at - started_at)/1000 as dur_sec FROM jobs WHERE status='failed' ORDER BY completed_at"

Common failure patterns:

• "stall detected" — server restarted while job was running. Check if server_id column exists (migration may be needed). Run tenet init --upgrade.
• "invocation timed out after Xms" — adapter timeout too short. Check tenet config for timeout setting. Default is 30 minutes.
• "Not inside a trusted directory" — git safe.directory issue. Run: git config --global --add safe.directory <project-path>
• "no agent adapter available" — the configured agent CLI is not installed or not in PATH.

5. Job timeline

# Full job execution timeline
sqlite3 .tenet/.state/tenet.db "SELECT datetime(started_at/1000, 'unixepoch', 'localtime') as started, datetime(completed_at/1000, 'unixepoch', 'localtime') as done, type, status, substr(json_extract(params, '$.name'), 1, 40) as name, (completed_at - started_at)/1000 as dur_sec FROM jobs WHERE started_at IS NOT NULL ORDER BY started_at"

6. Event log

# Recent events (last 20)
sqlite3 .tenet/.state/tenet.db "SELECT datetime(timestamp/1000, 'unixepoch', 'localtime') as time, job_id, event, substr(data, 1, 100) as data FROM events ORDER BY id DESC LIMIT 20"

# Check for orphaned job resets
sqlite3 .tenet/.state/tenet.db "SELECT * FROM events WHERE event='orphaned_jobs_reset'"

7. Config check

# SQLite config
sqlite3 .tenet/.state/tenet.db "SELECT * FROM config"

# JSON config (source of truth)
cat .tenet/.state/config.json

The JSON config file is the source of truth. On server startup, it overwrites SQLite config values. If they disagree, the JSON values win.

8. Steer messages

# Pending steer messages
sqlite3 .tenet/.state/tenet.db "SELECT id, class, status, substr(content, 1, 80) as content FROM steer_messages WHERE status != 'resolved' ORDER BY timestamp"

9. Git vs DB desync check

# Compare git commits to completed dev jobs
# Git commits with tenet prefix
git log --oneline --grep="tenet(" | head -20

# Completed dev jobs
sqlite3 .tenet/.state/tenet.db "SELECT substr(json_extract(params, '$.name'), 1, 50) as name FROM jobs WHERE type='dev' AND status='completed'"

# Pending dev jobs (check if any were implemented outside MCP)
sqlite3 .tenet/.state/tenet.db "SELECT substr(json_extract(params, '$.name'), 1, 50) as name FROM jobs WHERE type='dev' AND status='pending'"

If git has commits for features that are "pending" in the DB, the agent bypassed the MCP pipeline. This usually happens when the MCP server crashed and the agent continued without it.

10. MCP server status

# Check if tenet serve process is running
ps aux | grep "tenet serve" | grep -v grep

# Check for background server PID file
cat .tenet/.state/server.pid 2>/dev/null

# Test MCP server connectivity (start in foreground to see errors)
tenet serve --project .

Common Issues and Fixes

Jobs stuck as "running" after server restart

The server_id mechanism should auto-recover these on restart. If it doesn't:

# Manual fix: reset stuck running jobs to pending
sqlite3 .tenet/.state/tenet.db "UPDATE jobs SET status='pending', started_at=NULL, last_heartbeat=NULL, server_id=NULL WHERE status='running'"

Eval jobs always timing out

Check adapter timeout: tenet config. Default is 30 min. For Playwright e2e jobs that need to start servers + run tests, this may need to be higher.

Agent using wrong CLI

# Check configured agent
sqlite3 .tenet/.state/tenet.db "SELECT * FROM config WHERE key='default_agent'"
cat .tenet/.state/config.json

# Verify agent is available
which claude && claude --version
which opencode && opencode --version
which codex && codex --version

Database locked errors

Tenet uses WAL mode for concurrent reads. If you see "database locked":

# Check for other processes holding the DB
fuser .tenet/.state/tenet.db 2>/dev/null || lsof .tenet/.state/tenet.db

Playwright MCP not working

# Check if installed
npm list -g @playwright/mcp
npx --no-install @playwright/mcp --help

# Check .mcp.json for playwright entry
cat .mcp.json | grep -A3 playwright

# Check if browsers are installed
npx playwright install --dry-run

Adapter picking the wrong model / wrong behavior

If an agent CLI works interactively but fails when invoked by Tenet as a subprocess, it's almost always because the subprocess sees a different default (model, auth profile, sandbox mode) than your interactive session.

Common symptom: opencode works for you manually, but Tenet-spawned opencode jobs fail with "model not available" or similar auth errors — because opencode run picked a built-in default model, not the one in your config.

Diagnose:

# See what adapter args Tenet is passing
cat .tenet/.state/config.json | grep -E "opencode_args|codex_args|claude_args"

# See what the CLI thinks its default is
opencode --help | head -30
codex --help | head -30
claude --help | head -30

Fix by pinning the flag Tenet should inject on every subprocess call:

tenet config --opencode-args "--model github-copilot/claude-opus-4-5"
tenet config --codex-args "--approval-mode never"
tenet config --claude-args "--allowedTools Bash,Read,Write,Edit"

Pass an empty string to clear a setting: tenet config --opencode-args "".

Restart the Tenet MCP server after changing adapter args — they're read at server startup.

Notes on the mechanism:

• Extra args are stored in .tenet/.state/config.json under claude_args / opencode_args / codex_args.
• They're injected per-CLI at the known-safe position (before run/exec, after --full-auto for Codex).
• Argument splitting is whitespace-based — values cannot contain embedded spaces in v1. If you need quoted values, file an issue.

Reporting

After running diagnostics, summarize:

1. Health: Is the DB healthy? Are there stuck jobs?
2. Timeline: What was the last successful job? When did things go wrong?
3. Root cause: What caused the failure? (timeout, stall, crash, config, etc.)
4. Recovery: What's the recommended fix?