fft debug
- Repo stars 0
- Author repo nano-core
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @0-CYBERDYNE-SYSTEMS-0 · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Docker
- Runtime requirements
- Docker
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# FFT Debug
Use this skill for incident triage and deterministic debugging of FFT_nano host and container paths.
## When to use this skill
- Use when runtime behavior is failing, degraded, or inconsistent.
- Use when investigating provider wiring, routing, logs, or IPC state.
- Use when producing reproducible triage output before any fix attempt.
## When not to use this skill
- Do not use as the default path for normal feature work.
- Do not use when the request is purely product behavior, not incident/debug.
- Do not use to justify destructive cleanup without explicit approval.
## Guardrails
- Never use destructive git commands unless explicitly requested.
- Preserve unrelated worktree changes.
- Keep admin/coder controls in main chat only; do not bypass main-chat restrictions.
## Fast Triage
1. Confirm single instance lock:
- `ls -la data/fft_nano.lock`
2. Check startup/runtime logs:
- `tail -n 200 logs/fft_nano.log`
- `tail -n 200 logs/fft_nano.error.log`
3. Check per-group container logs:
- `ls -la groups/<group>/logs`
- `tail -n 200 groups/<group>/logs/*`
4. Inspect registration + IPC state:
- `cat data/registered_groups.json`
- `find data/ipc -maxdepth 3 -type f`
## Common Failure Modes
- Provider key missing: Pi reports no models available.
- Wrong `PI_API`/`PI_MODEL`: model/provider not found.
- Multiple bot instances: Telegram getUpdates conflict.
- Docker daemon unavailable or runtime permission issues.
## Recommended Debug Commands
- Build/runtime checks:
- `npm run typecheck`
- `npm test`
- Dry-run routing check (no live model call):
- `FFT_NANO_DRY_RUN=1 ./scripts/start.sh dev telegram-only`
- Runtime detail logging:
- `LOG_LEVEL=debug ./scripts/start.sh dev telegram-only`
## Telegram Debug Path
- Verify bot token present at runtime.
- In bot DM: `/id`, `/status`, `/help`.
- Admin checks in main chat only: `/tasks`, `/groups`, `/panel`, `/coder`, `/coder-plan`.
- If `/main <secret>` fails, verify `TELEGRAM_ADMIN_SECRET` and restart.
## Container Runtime Debug
- Docker runtime:
- `docker info`
- `docker ps`
- Host runtime (unisolated):
- verify explicit flags: `CONTAINER_RUNTIME=host`, `FFT_NANO_ALLOW_HOST_RUNTIME=1`
## Database/State Debug
- SQLite file location: `store/messages.db`
- Router state: `data/router_state.json`
- Group registry: `data/registered_groups.json`
- Per-group Pi state: `data/pi/<group>/.pi/`
Sections and files
Listed in source order.
sections -> When to use this skill → When not to use this skill → Guardrails → Fast Triage → Common Failure Modes → Recommended Debug Commands
terms -> Use this skill for incident triage and deterministic debugging of FFTnano host and container paths. · - Use when runtime behavior is failing, degraded, or inconsistent. · - Do not use as the default path for normal feature work. · - Never use destructive git commands unless explicitly requested. · 1. Confirm single instance lock: - ls -la data/fftnano.lock 2. · - Provider key missing: Pi reports no models available. · - Verify bot token present at runtime.
files/cmd -> ls -la data/fft_nano.lock · tail -n 200 logs/fft_nano.log · tail -n 200 logs/fft_nano.error.log · ls -la groups/<group>/logs · tail -n 200 groups/<group>/logs/* · cat data/registered_groups.json · find data/ipc -maxdepth 3 -type f · PI_API
body sha256 -> 1aefc08d3f0c
When to use this skill
Use when runtime behavior is failing, degraded, or inconsistent. Use when investigating provider wiring, routing, logs, or IPC state. Use when producing reproducible triage output before any fix attempt.
When not to use this skill
Do not use as the default path for normal feature work. Do not use when the request is purely product behavior, not incident/debug. Do not use to justify destructive cleanup without explicit approval.
Guardrails
Never use destructive git commands unless explicitly requested. Preserve unrelated worktree changes. Keep admin/coder controls in main chat only; do not bypass main-chat restrictions.
Fast Triage
Confirm single instance lock:
ls -la data/fft_nano.lockCheck startup/runtime logs:tail -n 200 logs/fft_nano.logtail -n 200 logs/fft_nano.error.logCommon Failure Modes
Provider key missing: Pi reports no models available. Wrong
PI_API/PI_MODEL: model/provider not found. Multiple bot instances: Telegram getUpdates conflict. Docker daemon unavailable or runtime permission issues.