task-persistence
Cross-session tasks via task-db.py or task_* MCP tools. v2: story/slices, paused, switch, bus-as-tasks, Telegram events.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- task-persistence
- author
- Steadfaste Fleet
- aliases
- [ "todo-persistence" ]
- version
- 2.1.0
- category
- devops
- metadata
- { "hermes": { "tags": [ "task", "persistence", "session", "postgres", "tasks", "protocol", "todo" ], "related_skills": [ "session-manager", "agent-fundamentals", "task-start", "session-start-discipline", "fleet-bus" ] } }
- platforms
- [ "linux", "macos" ]
- description
- Cross-session tasks via task-db.py or task_* MCP tools. v2: story/slices, paused, switch, bus-as-tasks, Telegram events.
03 SKILL.md 正文
Task Persistence — Cross-Session Task Tracking (tasks schema)
Why This Exists
The Hermes todo() tool is per-session — items set in one session vanish
when the next starts. This skill documents the durable task system on the
tasks schema of each host's mycortex-postgres (party-reviewed design 2026-08-06:
docs/design/task-workflow.md). Task Lifecycle v2 (2026-08-06,
docs/design/task-lifecycle-v2.md) adds story/slices, paused, switch,
bus-commands-as-tasks, and Telegram visibility.
History: the old system (bus.todos + todo-db.py) was retired 2026-08-06 —
bus.todos never existed on workers (bus schema is orchestrator-only), and
todo-db.py silently no-op'd (stdin-mode psql rc=0). The tasks schema is
applied on EVERY host by fleet-update.sh via the version-gated runner.
Architecture
Agent Session
│
├── todo() ──► ephemeral (Hermes tool, per-session)
│
└── task-db.py ──► tasks.tasks (per-host mycortex-postgres)
│ │
├─ CLI ├─ RLS per-profile isolation (fail-closed)
└─ task-mcp.py├─ CRUD as mycortex_reader_<profile> (never superuser)
(MCP tools) └─ Survives crashes, restarts, disconnects
└─ task_events → telegram_notify → Luke's DM
Database
- Schema:
ops/services/tasks/schema/v00X__*.sql(version-gated bytasks.schema_version; applied byops/services/tasks/migrate.py). Current: v007 — v005 added hierarchy/paused/correlation/events, v006 added reader SELECT on schema_version, v007 fixed task_upsert partial-update preservation. - Table:
tasks.tasks(active),tasks.task_archive(historical),tasks.task_events(append-only audit + notify source of truth) - Functions:
tasks.task_upsert(),tasks.task_list(),tasks.task_archive_old(),tasks.task_prune(),tasks.task_log_event(),tasks.transition_allowed() - RLS: personal rows visible to own profile only; fleet rows visible to all, writable only by fleet writers (orchestrator profiles); fleet × client-project and path/email/IP content banned (PII scrub gate)
Identity — NEVER hostname (Luke 2026-08-10)
Agent identity (PROFILE, CRUD_ROLE) resolves from, in order:
HERMES_PROFILE env → AGENT_NAME env → AGENT_NAME in
~/.steadfaste-fleet/agent.env → ~/steadfaste-fleet/.env → ~/steadfaste-fleet/.env.
There is NO hostname/whoami fallback — if no agent variable is found,
task-db.py exits 1 with a clear error. A misconfigured host fails loudly
instead of silently writing rows as the machine name. Same rule in
commands.py (handler dispatch) — it raises RuntimeError.
CLI + MCP
- Deployed to:
~/.steadfaste-fleet/scripts/task-db.py(register in fleet-update.sh) - MCP server:
mcp-servers/task-mcp.py, registered astodos(tools: task_add, task_list, task_pending, task_update, task_switch, task_save_end, task_prune). All agents — not orchestrator-only. - Queries are repo-scoped (2026-10-14, reported by Titus):
list,pending,--board,--claimableand--handed-outshow the CALLER's repo plus untagged rows — another named repo's tasks are never returned. The repo comes from--repo, else the repo the enforcer injected for your session, elseFLEET_SESSION_REPO, else the git repo at the working directory; if none of those exist the query returns NOTHING (never every repo's tasks). The fleet-wide view is the EXPLICIT--repo ALL/{"repo": "ALL"}.
Commands
# List my tasks (union of personal + locally-present fleet rows)
task-db.py list [--status pending|in_progress|paused|completed|cancelled]
task-db.py list --project steadfaste-fleet --repo steadfaste-fleet
# Add a task (tag it: project/repo/scope/source). v2: story/slice hierarchy.
task-db.py add "Fix dashboard health check" --priority 2 \
--project steadfaste-fleet --repo steadfaste-fleet --scope personal --source manual
task-db.py add "Story: fleet observability" --kind story
task-db.py add "Slice: bus task wiring" --kind slice --parent <story-uuid>
task-db.py add "EXEC: fleet-doctor.py" --source inbox --correlation-id <corr>
# Update status (canonical lifecycle; column=done on completed)
task-db.py update <id> --status in_progress
task-db.py update <id> --status completed
task-db.py update <id> --status paused # v2: pause
task-db.py update <id> --status in_progress --reason reopen # reopen a done task
task-db.py update --by-correlation <corr> --status completed # bus-linked task
# NO-OP RULE: a same-status update records nothing (the event trigger skips
# it — v005__lifecycle.sql). So `--reason` with an unchanged status is
# REFUSED (exit 1) rather than silently dropped, and a bare same-status update
# prints "already <status> — no change" and issues no UPDATE. After a real
# transition with --reason the CLI re-reads the event trail and fails if the
# reason did not land. To record a note that is not a status change, use a
# governance issue event — do not pass it as `update --reason`.
# Switch: pause current in_progress + resume target (one atomic command)
task-db.py switch <target-id>
# Session start: print pending as JSON for todo() restore
task-db.py pending # inbox rows carry "untrusted": true
task-db.py restore <pending.json> # skips untrusted inbox rows
task-db.py restore <pending.json> --include-inbox # force (untrusted!)
# Session end: archive completed/cancelled, report remaining
task-db.py save-end
# Prune archived rows older than N (never touches active rows)
task-db.py prune --older-than 90d
# Apply schema (delegates to ops/services/tasks/migrate.py as DB owner)
task-db.py --apply-schema
# Suppress the Telegram event for a single command
task-db.py update <id> --status completed --no-notify
Session Protocol
Session Start
todo()— load in-memory state (usually empty)task-db.py pending— query DB for your profile's pending items (JSON). Paused rows are surfaced but NEVER auto-resumed (M-9). Inbox-derived rows are marked"untrusted": trueand are excluded from restore by default (R-4 — bus content is not trusted as agent instructions).- Restore with
task-db.py restore <pending.json>(skips untrusted).
Throughout Session
- Before each
begin_change():task-db.py update <id> --status in_progress - When switching tasks:
task-db.py switch <target-id>(atomic pause+resume) - After each
end_change():task-db.py update <id> --status completed - Reopen a completed task deliberately:
--reason reopen(never casual)
Session End
task-db.py save-end— archives completed/cancelled items- Remaining
pending/in_progress/pauseditems persist in DB for next session
Bus Commands as Tasks (v2 S4/S5)
The fleet handler (agent-message-handler.py) creates a tasks.tasks row
(source='inbox', linked by correlation_id) for tracked subjects:
EXEC, UPDATE_REQUEST, TASK_REQUEST (Task: prefix), PROPOSAL,
ISSUES, IMPROVEMENTS. Lifecycle:
| Command class | Consumer | Transitions |
|---|---|---|
| EXEC / UPDATE_REQUEST | handler (no_agent) | created(pending) on receipt → in_progress at dispatch → completed at Result-receipt (EXEC_RESULT handler path) |
| ISSUES / PROPOSAL / IMPROVEMENTS / Task: | LLM inbox_read session |
created(pending) on handler receipt → in_progress when the orchestrator processes it → completed when handled — the session calls task-db.py update --by-correlation <corr> --status completed |
- Stale sweep: the handler pauses inbox tasks stuck
in_progress> 1h (TASKS_STALE_HOURS) with reason='stale' on every tick. - Telegram: entry + completed events notify Luke's DM via
lib/telegram_notify.py([agent] story → slice: status (id)). Mute viaTASKS_NOTIFY_MUTE=in_progress,paused; quiet hours viaTASKS_NOTIFY_QUIET=22:00-07:00. - Never silently drop: a handled ISSUES/PROPOSAL must be transitioned to
completed (or paused if deferred). See
fleet-busskill.
Honest Fleet Semantics (party B-3)
--scope fleet stores the row locally on this host only — it is NOT
visible fleet-wide until transport ships (roadmap: git-backed, private repo).
The CLI prints this warning. Never claim fleet-wide visibility in reports.
Security Invariants (party B-1/B-2)
- Identifier-ish values (agent/project/repo/target/assignee/scope/status/
source/column/kind) are allowlist-validated BEFORE use; all DML funnels
through the parameterized
tasks.task_upsert()— never string-built WHERE clauses. - Free text is quote-doubled into string literals only.
- psql runs with
ON_ERROR_STOP=1; query flows via STDIN, never embedded in a shell command string (the old sg-embedding path was shell-RCE). - CRUD connects as
mycortex_reader_<profile>— NEVER superuser. - v007 partial-update fix: status-only updates preserve source/scope/
priority/project/created_by (a bus task stays
source='inbox'through its lifecycle). Do not revert toCOALESCE(EXCLUDED.x, ...)in task_upsert.
Anti-Patterns
- ❌ Relying only on
todo()tool — per-session. Items vanish. - ❌ Using a local file for persistence — the DB is already there.
- ❌ Letting completed items accumulate — run
task-db.py save-end. - ❌ Forgetting to update status — stale pending items clutter restore.
- ❌ Hardcoding UUIDs — retrieve via
task-db.py pending/list. - ❌ Using bus. or todo- nomenclature** — the tasks system is
tasks.*,task-db.py,task_*tools everywhere (AC-1). - ❌ Hostname identity fallback — identity comes from AGENT_NAME env / .env, never platform.node() (Luke 2026-08-10).
Doctor Checks (v2 S7)
The doctor's check_task_lifecycle_v2 FAILs/WARNs on: schema_version < 5
(FAIL), task_events RLS forgeable grants (FAIL), telegram notify failures
(WARN), stale inbox tasks (WARN), .env perms != 600 (WARN). Run the doctor
after any schema/deploy change.
Known Issues
✅ FIXED 2026-08-06 — silent failure class (rc=0 stdin bug)
The old todo-db.py printed ✅ while rows vanished (stdin-mode psql returns
rc=0 on SQL error; bus.todos never existed on the migrated DB). The rewrite
uses -c/ON_ERROR_STOP + stderr scan; errors exit 1 with evidence. The
doctor now runs a write-probe (seed → list → archive) to catch the
"valid JSON but dead table" class — see check_task_db.
✅ FIXED 2026-08-10 — v007 partial-update clobber (found live in S3 e2e)
v005's task_upsert ON CONFLICT used COALESCE(EXCLUDED.x, existing) but
EXCLUDED.x is never NULL (INSERT defaults) → every status-only update
clobbered source (inbox→manual), scope (fleet→personal), priority (→0),
project (→steadfaste-fleet), created_by. v007 fixes the DO UPDATE clause to
coalesce against the function parameter. Regression-locked in
test-tasks-schema.sh.
Reference
- Design:
~/steadfaste-fleet/docs/design/task-workflow.md - Lifecycle v2:
~/steadfaste-fleet/docs/design/task-lifecycle-v2.md - CLI:
~/steadfaste-fleet/ops/scripts/manage/task-db.py - MCP:
~/steadfaste-fleet/mcp-servers/task-mcp.py - Migration runner:
~/steadfaste-fleet/ops/services/tasks/migrate.py - Notify:
~/steadfaste-fleet/ops/scripts/lib/telegram_notify.py - psql pitfalls: skill
psql-automation - Session restore: skill
session-start-discipline
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.