# pi-config

Personal Pi configuration for **sebasfavaron**.

## Included
- `AGENTS.md`
- `MIGRATION.md`
- `settings.json`
- `extensions/subagent/`
- `extensions/questionnaire.ts`
- `extensions/session-memory-prompt.ts`
- `scripts/apply-pi-shutdown-hook-patch.py`
- `scripts/session-memory-analyzer.py`
- `scripts/session-memory-dispatcher.py`
- `scripts/install-session-memory-dispatcher.service`
- `bin/pi-loop` repeated multi-session task runner
- `docs/pi-loop.md` usage guide for repeated multi-session loops
- `bin/tmp-cleanup` / `/tmp` cleanup tool
- `scripts/install-tmp-cleanup-cron.sh` cron installer for /tmp cleanup
- `bin/laptop-*` remote laptop helper scripts
- `bin/laptop-write` atomic remote file writer for laptop files

## Goal

Make this repo both the source of truth **and the live Pi config directory**.

## Layout

Canonical layout lives in:
- `docs/system-layout.md`

Loose cross-session backlog lives in:
- `docs/BACKLOG.md`

Current roots:
- control plane: `/home/sebas/pi-config`
- durable memory: `/home/sebas/agents-database`
- runtime: `/home/sebas/runtime`
- work: `/home/sebas/work`
- outputs: `/home/sebas/outputs`
- archive: `/home/sebas/archive`

## Notes

- Direct, compressed, low-noise communication is the default style.
- Session close hook can still queue memory analysis before switch/fork/exit.
- Session memory uses an external local dispatcher on `127.0.0.1:17882`; the hook captures session identity/context and enqueues metadata under `sessions/session-memory-jobs/`.
- `scripts/session-memory-sweeper.py` is the reliable catch-up path for Telegram-heavy periods: it scans recent session files, skips obvious loop noise, and analyzes anything not yet processed.
- The analyzer first tries cheap `pi` model analysis (`gpt-5.4-mini`, thinking off); if that path is unavailable, it falls back to a deterministic episode-summary candidate instead of failing silently.
- The canonical memory pipeline lives in `agents-database` (`MemoryService` / `MemoryEngine`). Repo-local helpers should only capture session context and hand off to that service.
- For unattended `pi` scripts and jobs, prefer explicit provider/model selection. Current safe default on this machine: `--provider openai-codex --model gpt-5.4-mini`.
- Use `./scripts/install-session-memory-dispatcher.service` for the dispatcher and `./scripts/session-memory-sweeper.{service,timer}` for periodic catch-up.
- The old `session_before_shutdown` runtime patch remains as fallback only if you choose to keep it enabled.
- Reapply the runtime patch after Pi upgrades only if you still use that fallback: `./scripts/apply-pi-shutdown-hook-patch.py`
- **Pending validation:** confirm the default communication mode auto-loads in every new Pi session.
- Top-level `/tmp` files older than 3 days are cleaned every 3 days via `bin/tmp-cleanup`.
- Install the cleanup cron with `scripts/install-tmp-cleanup-cron.sh`.
- Remote laptop workflow can be driven from this Pi using `bin/laptop-run`, `bin/laptop-read`, `bin/laptop-write`, `bin/laptop-rsync`, `bin/laptop-mount`, and `bin/laptop-umount` against host `sebastians-macbook-pro-2`.

## Local server routes on `ballbox-first`

Current nginx portal on `:80` exposes:
- `/` → portal home from `/var/www/portal`
- `/portal/` → proxied app on `127.0.0.1:18789`
- `/calistenia/` → static files from `/home/sebas/clawd/web/calistenia/`
- `/files/` → copyparty file server on `127.0.0.1:3923`
- `/mp3-share/` → static directory listing from `/home/sebas/downloads/mp3-share/`
- `/gastos-europa/` → app de revisión/clasificación de gastos del viaje Europa en `127.0.0.1:18896`

Implementation notes:
- nginx route lives in `/etc/nginx/sites-available/kiosk`
- portal home link lives in `/var/www/portal/index.html`
- nginx access to `/home/sebas/downloads/mp3-share/` depends on ACLs that allow user `www-data` to traverse `/home/sebas` and read that subtree
- `downloads/` is the shared/download-served tree; `Downloads/` is the desktop/user inbox
- `gastos-europa` project doc lives at `/home/sebas/work/gastos-europa/README.md`

## Remote laptop helpers

Default host is `sebastians-macbook-pro-2`. Override with `LAPTOP_HOST` if needed.

Examples:
- `bin/laptop-run 'uname -a'`
- `bin/laptop-read /Users/sebas/.zshrc | sed -n '1,40p'`
- `bin/laptop-rsync sebastians-macbook-pro-2:/Users/sebas/Downloads/file ./`
- `bin/laptop-rsync ./localfile sebastians-macbook-pro-2:/Users/sebas/Downloads/`
- `printf 'new contents\n' | bin/laptop-write /Users/sebas/Downloads/test.txt`
- `bin/laptop-write --from ./localfile /Users/sebas/Downloads/test.txt`
- `bin/laptop-mount /Users/sebas/Downloads downloads` then work at `~/mnt/laptop/downloads`

## Batch `pi` helpers

Two first-class helpers:

- `bin/pi-loop`: run the same task through multiple sequential `pi` sessions so later passes can reinforce and refine earlier work.
- `bin/pi-job-*`: run one detached inspectable batch job with status/check/wait/stop flow.

Decision rule:

- multiple passes on the same prompt -> `pi-loop`
- one detached batch run -> `pi-job-*`

Unattended helpers should avoid implicit model/provider resolution.

- `bin/pi-loop` defaults to `--provider openai-codex --model gpt-5.4-mini --thinking low` and still lets you override via flags.
- `bin/pi-job-runner` forces `--provider openai-codex --model gpt-5.4-mini --thinking low` by default.
- `pi-job-*` overrides per process with env vars: `PI_PROVIDER`, `PI_MODEL`, `PI_THINKING`.

Start here:
- `docs/pi-loop.md`

Examples:
- `bin/pi-loop --count 3 --cwd /tmp/test --prompt "Touch one file"`
- `PI_MODEL=gpt-5.4 bin/pi-job-start --cwd /path/repo --prompt "Do the task"`

## /tmp cleanup

Top-level `/tmp` files older than 3 days are cleaned every 3 days.

- `bin/tmp-cleanup [--dry-run]`
- `scripts/install-tmp-cleanup-cron.sh`