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:

Before mutating anything, preserve evidence and prefer read-only checks. If the installed Tenet has DB maintenance commands, start with:

tenet db check --project .

If that reports unsafe, do not run manual UPDATE, VACUUM, checkpoint, or restore commands against the live DB. First archive the current .tenet/.state files and coordinate with the user.

1. Project structure check

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

Expected lifecycle directories: project/, project/design-components/, runs/, archive/, knowledge/, status/, state-snapshot/, and .state/. Pre-lifecycle projects may also have legacy lanes that tenet init --upgrade migrates into archive/legacy-v1/: spec/, interview/, decomposition/, harness/, journal/, visuals/, bootstrap/, steer/, and knowledge/. .state/ should contain tenet.db and optionally config.json.

2. Database health

# Check DB exists and is readable. Use Tenet's command when available.
tenet db check --project .

# Fallback: SQLite checks
sqlite3 .tenet/.state/tenet.db "PRAGMA integrity_check"
sqlite3 .tenet/.state/tenet.db "PRAGMA quick_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

2a. WAL/base mismatch checks

If .tenet/.state/tenet.db-wal exists, the normal SQLite view includes WAL frames. Compare the normal WAL-backed view with the immutable base DB view:

ls -la .tenet/.state/tenet.db*

# Normal view: tenet.db plus WAL
sqlite3 .tenet/.state/tenet.db "PRAGMA integrity_check"

# Base DB only: ignores WAL
sqlite3 'file:.tenet/.state/tenet.db?immutable=1' "PRAGMA integrity_check"

# Compare indexed counts vs forced table scans
sqlite3 .tenet/.state/tenet.db "SELECT status, COUNT(*) FROM jobs GROUP BY status ORDER BY status"
sqlite3 .tenet/.state/tenet.db "SELECT status, COUNT(*) FROM jobs NOT INDEXED GROUP BY status ORDER BY status"
sqlite3 .tenet/.state/tenet.db "SELECT COUNT(*) FROM jobs WHERE parent_job_id IS NULL"
sqlite3 .tenet/.state/tenet.db "SELECT COUNT(*) FROM jobs NOT INDEXED WHERE parent_job_id IS NULL"

Interpretation:

• Normal view fails but immutable base is ok: suspect WAL/base mismatch. Do not checkpoint. Preserve tenet.db, tenet.db-wal, and tenet.db-shm.
• Indexed and NOT INDEXED counts differ: indexes are unsafe even if some status queries still appear to work.
• Both normal and immutable views fail: the main DB image is already malformed.

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 120 minutes.
• "Not inside a trusted directory" from Codex — project trust is missing or marked untrusted in .codex/config.toml. Run tenet init --upgrade and accept the Codex trust prompt, or edit the project block to set trust_level = "trusted". If Git itself reports "dubious ownership", then add the project to Git's safe directory list with 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. First run tenet db check --project . or the read-only integrity checks above. Only if the DB is healthy should you consider manual state repair:

# 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 120 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
lsof .tenet/.state/tenet.db-wal 2>/dev/null
lsof .tenet/.state/tenet.db-shm 2>/dev/null

Creating a safe DB backup

Do not copy only .tenet/.state/tenet.db while WAL files may exist. Prefer:

tenet db backup --project .

Fallback if the command is unavailable and the DB is healthy:

sqlite3 .tenet/.state/tenet.db "VACUUM INTO '.tenet/.state/tenet-backup.db'"
sqlite3 .tenet/.state/tenet-backup.db "PRAGMA integrity_check"

Playwright MCP not working

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

# Check every agent config for playwright entry
cat .mcp.json | grep -A3 playwright
cat .codex/config.toml | grep -A6 playwright
cat opencode.json | grep -A6 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 '--config approval_policy="never"'
tenet config --codex-args-interaction-e2e "--dangerously-bypass-approvals-and-sandbox"
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, with optional job-scoped keys such as codex_args_interaction_e2e.
• They're injected per-CLI at the known-safe position. Codex defaults to --sandbox workspace-write; global or job-scoped sandbox flags override that default.
• 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?