deskd 0.1.0__tar.gz

deskd-0.1.0/.env.example

@@ -0,0 +1,63 @@
+# deskd configuration — copy to .env and fill in. NEVER commit .env.
+
+# Coordination DB (SQLite, WAL). Default: ./data/deskd.db
+DESKD_DB=
+# Base dir used to derive the default DB path. Default: the process cwd.
+DESKD_HOME=
+
+# --- supervisor console auth -------------------------------------------------
+# simple | signed | hybrid.
+#   simple — one shared access code over a trusted local network. Convenient,
+#            and only as strong as the code: it proves someone knows a secret,
+#            not who acted.
+#   signed — short-lived Ed25519 assertions signed on a trusted device. The
+#            public key is read from /etc/deskd/supervisor_ed25519.pub, which
+#            must be root-owned; that path is fixed and deliberately NOT
+#            settable here, because an agent that could repoint it could mint
+#            its own identity. Keep the private key OFF this host.
+#   hybrid — both accepted.
+# NOTE: the default (simple) leaves the signed path disabled.
+DESKD_SUPERVISOR_AUTH_MODE=simple
+
+# simple mode: the access code. Generate a strong one, e.g.
+#   python3 -c "import secrets;print(secrets.token_urlsafe(18))"
+# If unset, the server generates one at startup and prints it to its terminal.
+# NEVER hardcode this into any client/static file — that publishes the credential.
+DESKD_SUPERVISOR_ACCESS_CODE=
+
+# --- web console -------------------------------------------------------------
+# `deskd serve` binds loopback by default: the console carries the supervisor
+# adapter, so exposing it on a network must be a deliberate act.
+DESKD_HOST=127.0.0.1
+DESKD_PORT=8000
+
+# --- escalation channels -----------------------------------------------------
+# deskd ships NO network code and no channels of its own: an escalation always
+# lands in the `outbox` (a ledger row the console renders), and a host registers
+# anything richer at startup:
+#
+#   from deskd.meetings import CallableChannel, register_channel
+#   register_channel(CallableChannel(
+#       "discord", send=lambda subject, text: post_webhook(text),
+#       available=lambda: bool(os.environ.get("MYAPP_DISCORD_WEBHOOK")),
+#   ))
+#
+# Credentials for those channels are the host's business and belong in the
+# host's own environment, not here.
+
+# --- wake driver (scripts/cron/wake_orchestrator.sh) -------------------------
+# The driver is DRY-RUN unless this is exactly 1. Watch logs/wake.log first.
+DESKD_WAKE_EXECUTE=0
+# DESKD_AGENT_CMD=claude
+# DESKD_WAKE_MODEL=claude-opus-4-8
+# DESKD_WAKE_TIMEOUT=1800
+# Tools a woken session may use. Append your host's own tools here — the engine
+# grants nothing by itself.
+# DESKD_WAKE_ALLOWED_TOOLS=Bash,Read,Write,Edit,Glob,Grep,Skill,ToolSearch,TodoWrite,WebSearch,WebFetch
+# DESKD_PYTHON=  # interpreter; defaults to ./.venv/bin/python, else python3
+# DESKD_BIN=     # deskd CLI; defaults to ./.venv/bin/deskd, else `deskd` on PATH
+# DESKD_LOG_DIR=
+
+# Exported by the driver into a spawned/resumed session, and read by the
+# PostToolUse hook (scripts/session_hook.py) to know which role it is serving.
+# DESKD_ROLE=

deskd-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# --- data / secrets: NEVER commit ---
+.env
+.env.*
+!.env.example
+*.db
+*.db-wal
+*.db-shm
+data/
+logs/
+*.log
+
+# --- python ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# --- os / editor ---
+.DS_Store
+*.swp
+.idea/
+.vscode/

deskd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hongdp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deskd-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: deskd
+Version: 0.1.0
+Summary: A domain-agnostic orchestration engine for multi-agent desks: presence, a unified inbox, bounded meetings, and a wake ladder that proves delivery.
+Project-URL: Homepage, https://github.com/hongdp/deskd
+Project-URL: Documentation, https://github.com/hongdp/deskd/blob/main/docs/design.md
+Project-URL: Source, https://github.com/hongdp/deskd
+Author: deskd contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,multi-agent,orchestration,scheduling,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
+Description-Content-Type: text/markdown
+
+# deskd
+
+**An orchestration engine for multi-agent desks.** deskd owns the part that is
+hard and domain-agnostic: knowing which agents are alive, what they're doing,
+what's queued for them, and — the difficult bit — **reliably waking the right
+agent at the right time and proving the message actually landed.**
+
+Your agents do the domain work. deskd does everything else.
+
+> Built for headless [Claude Code](https://claude.com/claude-code) agents
+> (`claude -p` + a `PostToolUse` hook), but the engine is a plain Python package
+> over SQLite with no hard dependency on any particular agent runtime.
+
+---
+
+## Why
+
+Multi-agent systems usually rot in the same three places:
+
+1. **Agents poll.** Every agent runs its own `sleep`/wake loop, burning tokens
+   to discover there's nothing to do — and still missing the thing that mattered.
+2. **Messages vanish.** "I sent it" ≠ "they read it." Nothing distinguishes
+   *notified* from *read*, so a stuck message is invisible until someone notices
+   hours later.
+3. **Nobody knows what's running.** Two sessions of the same role stomp each
+   other; a crashed agent looks identical to an idle one.
+
+deskd's position: **agents must never manage their own waking.** They end their
+turn and the orchestrator wakes them — on a timer, on a calendar, on a custom
+watcher, on a message, or on an escalation ladder when a wake doesn't land.
+
+## What you get
+
+| | |
+|---|---|
+| **Presence** | One live session per role, enforced by a role-scoped `flock`. Heartbeats from the in-session hook; crash-safe (the kernel releases the lock). |
+| **Unified inbox** | Every notification — alerts, signals, system events, meeting messages — lands in one queue per role, with per-key dedup so a re-firing alert never piles up. |
+| **Wake orchestration** | Collect demand → route by presence → record the attempt → **verify the loop closed** → escalate. A wake that doesn't land climbs: in-session hook → resume → spawn → human (Discord/email) → a red badge on the supervisor console that never times out. |
+| **Self-service wake hooks** | An agent registers its own wakes: `--at` (one-shot), `--every` (interval), `--cron` (calendar, DST-correct), or `--probe` (**your own watcher function** — return a dict and it wakes you). |
+| **Delivery ledger** | Per message × recipient: `queued → notified → read`. Past SLA and unread with nobody reacting = **`overdue`** — surfaced red. Rows are a projection of durable messages, so a delivery can't be silently lost. |
+| **Bounded meetings** | Multi-agent meetings with check-in/quorum, mandatory 1:1 replies with an SLA, message budgets, and a mutual termination handshake. Bounded by construction — no infinite agent chatter. |
+| **Cross-session tasks** | Work items that outlive a session. Soft deadlines (`due_at`) sort to the top but **never wake anyone**; only `priority=urgent` does. |
+| **Session lifecycle** | Intraday continuity, cross-day rollover: wind the old session down with a handoff, start fresh the next day. |
+| **Supervisor console** | A web board (live status + queue + hooks + wake activity), a per-agent detail page with full execution history, and a meetings console — behind an access-code or Ed25519 trusted-device gate. |
+
+## Install
+
+```bash
+pip install -e ".[web]"      # engine + web console
+```
+
+## Quickstart
+
+Describe your desk in a module that defines `configure_deskd()`:
+
+```python
+# myapp/desk.py
+from deskd.config import RoleSpec, PromptBuilder, configure
+
+class MyPrompts(PromptBuilder):
+    def bootstrap(self, role: str) -> str:
+        return f"Load the myapp skill, declare role={role}, follow its playbook."
+
+def configure_deskd():                        # deskd calls this at startup
+    configure(
+        roles=(
+            RoleSpec("researcher", "Researcher", ("research", "review")),
+            RoleSpec("operator",   "Operator",   ("execution",), {"can_execute": True}),
+        ),
+        timezone="America/New_York",
+        inbox_sources=("alert", "signal", "system", "meeting", "supervisor"),
+        probe_allowlist=("myapp.watchers",),   # empty = no probes may run
+        prompt_builder=MyPrompts(),
+    )
+```
+
+Point deskd at it with **`DESKD_CONFIG_MODULE`**. Every deskd process — the CLI,
+`deskd serve`, the cron driver — imports that module and calls `configure_deskd()`
+before it touches the engine, so your roles are registered everywhere. Without it
+a deskd process starts empty (no roles) and every role-scoped command is rejected.
+
+```bash
+export DESKD_CONFIG_MODULE=myapp.desk         # (myapp must be importable — on PYTHONPATH)
+
+deskd serve                                   # supervisor console on 127.0.0.1:8000
+deskd status set --role operator --activity "watching the queue"
+deskd inbox enqueue --for operator --source alert --title "threshold crossed" --priority urgent
+deskd wake sources --role operator            # what can wake me, and how to change it
+```
+
+Wake the desk from cron (the driver is the **only** thing that spawns sessions):
+
+```cron
+# cron has its own environment — set both vars on the line (or in the crontab header)
+* * * * * DESKD_CONFIG_MODULE=myapp.desk DESKD_WAKE_EXECUTE=1 /path/to/deskd/scripts/cron/wake_orchestrator.sh
+```
+
+It is **dry-run by default** — schedule it, watch the log, then set
+`DESKD_WAKE_EXECUTE=1` when the decisions look right.
+
+### Agents schedule themselves — declaratively
+
+```bash
+# a calendar wake (weekday 06:15, in your configured tz)
+deskd hook add --for operator --title "daily digest" --cron "15 6 * * *"
+
+# your own watcher algorithm: return a dict -> it wakes you
+deskd hook add --for operator --title "queue depth watch" \
+  --probe myapp.watchers:queue_depth --every 600
+```
+
+```python
+# myapp/watchers.py — a probe may observe and notify. Nothing else.
+def queue_depth():
+    n = measure()
+    if n > 100:
+        return {"title": f"queue at {n}", "priority": "urgent"}
+    return None          # None = don't wake anyone
+```
+
+Three consecutive probe errors auto-disable the hook and notify its owner — a
+broken watcher can't rot silently or stall the tick.
+
+## Design notes
+
+**Headless sessions can't be interrupted mid-turn.** So "deliver to the agent"
+means two things: while it's running, its `PostToolUse` hook surfaces the queue
+into context; while it's idle, the orchestrator resumes its session with the
+queued items as the prompt. "Current session" = a *resumable session id*, not a
+live process.
+
+**Storage is SQLite (WAL) and it is the only source of truth.** No broker, no
+daemon holding state. Every tick rebuilds its decisions from the DB, so a
+crashed orchestrator self-heals on the next tick. SQLite can't wake a dormant
+process — the engine doesn't pretend otherwise; it makes every wake attempt an
+auditable row with a closed loop and an escalation path.
+
+**Nothing here executes your domain.** The engine wakes agents and delivers
+notifications. It never acts *as* an agent, and it has no path to your
+side-effecting systems.
+
+## Security
+
+- The supervisor is **not** an agent role: agent APIs reject it, and supervisor
+  actions only enter through the authenticated web adapter.
+- `simple` mode = an access code (convenience, trusted host). `signed` mode =
+  short-lived Ed25519 assertions from a trusted device; the public key path is
+  fixed at `/etc/deskd/supervisor_ed25519.pub`, must be root-owned, and is
+  deliberately **not** environment-overridable — an agent must not be able to
+  point verification at a key it wrote. Keep the private key off the host.
+- **Never hardcode the access code into a client/static file.** A pre-filled
+  credential in page source *is* the credential. (Ask us how we know.)
+- Probes only import from your explicit `probe_allowlist`. Empty = deny all.
+
+See [`docs/security.md`](docs/security.md).
+
+## Docs
+
+- [`docs/design.md`](docs/design.md) — architecture and the decisions behind it
+- [`docs/roadmap.md`](docs/roadmap.md) — where this is going, in dependency order
+- [`skills/agent-orchestration/`](skills/agent-orchestration/) — a skill teaching an agent to operate and evolve a deskd desk
+
+## License
+
+MIT

deskd-0.1.0/README.md

@@ -0,0 +1,165 @@
+# deskd
+
+**An orchestration engine for multi-agent desks.** deskd owns the part that is
+hard and domain-agnostic: knowing which agents are alive, what they're doing,
+what's queued for them, and — the difficult bit — **reliably waking the right
+agent at the right time and proving the message actually landed.**
+
+Your agents do the domain work. deskd does everything else.
+
+> Built for headless [Claude Code](https://claude.com/claude-code) agents
+> (`claude -p` + a `PostToolUse` hook), but the engine is a plain Python package
+> over SQLite with no hard dependency on any particular agent runtime.
+
+---
+
+## Why
+
+Multi-agent systems usually rot in the same three places:
+
+1. **Agents poll.** Every agent runs its own `sleep`/wake loop, burning tokens
+   to discover there's nothing to do — and still missing the thing that mattered.
+2. **Messages vanish.** "I sent it" ≠ "they read it." Nothing distinguishes
+   *notified* from *read*, so a stuck message is invisible until someone notices
+   hours later.
+3. **Nobody knows what's running.** Two sessions of the same role stomp each
+   other; a crashed agent looks identical to an idle one.
+
+deskd's position: **agents must never manage their own waking.** They end their
+turn and the orchestrator wakes them — on a timer, on a calendar, on a custom
+watcher, on a message, or on an escalation ladder when a wake doesn't land.
+
+## What you get
+
+| | |
+|---|---|
+| **Presence** | One live session per role, enforced by a role-scoped `flock`. Heartbeats from the in-session hook; crash-safe (the kernel releases the lock). |
+| **Unified inbox** | Every notification — alerts, signals, system events, meeting messages — lands in one queue per role, with per-key dedup so a re-firing alert never piles up. |
+| **Wake orchestration** | Collect demand → route by presence → record the attempt → **verify the loop closed** → escalate. A wake that doesn't land climbs: in-session hook → resume → spawn → human (Discord/email) → a red badge on the supervisor console that never times out. |
+| **Self-service wake hooks** | An agent registers its own wakes: `--at` (one-shot), `--every` (interval), `--cron` (calendar, DST-correct), or `--probe` (**your own watcher function** — return a dict and it wakes you). |
+| **Delivery ledger** | Per message × recipient: `queued → notified → read`. Past SLA and unread with nobody reacting = **`overdue`** — surfaced red. Rows are a projection of durable messages, so a delivery can't be silently lost. |
+| **Bounded meetings** | Multi-agent meetings with check-in/quorum, mandatory 1:1 replies with an SLA, message budgets, and a mutual termination handshake. Bounded by construction — no infinite agent chatter. |
+| **Cross-session tasks** | Work items that outlive a session. Soft deadlines (`due_at`) sort to the top but **never wake anyone**; only `priority=urgent` does. |
+| **Session lifecycle** | Intraday continuity, cross-day rollover: wind the old session down with a handoff, start fresh the next day. |
+| **Supervisor console** | A web board (live status + queue + hooks + wake activity), a per-agent detail page with full execution history, and a meetings console — behind an access-code or Ed25519 trusted-device gate. |
+
+## Install
+
+```bash
+pip install -e ".[web]"      # engine + web console
+```
+
+## Quickstart
+
+Describe your desk in a module that defines `configure_deskd()`:
+
+```python
+# myapp/desk.py
+from deskd.config import RoleSpec, PromptBuilder, configure
+
+class MyPrompts(PromptBuilder):
+    def bootstrap(self, role: str) -> str:
+        return f"Load the myapp skill, declare role={role}, follow its playbook."
+
+def configure_deskd():                        # deskd calls this at startup
+    configure(
+        roles=(
+            RoleSpec("researcher", "Researcher", ("research", "review")),
+            RoleSpec("operator",   "Operator",   ("execution",), {"can_execute": True}),
+        ),
+        timezone="America/New_York",
+        inbox_sources=("alert", "signal", "system", "meeting", "supervisor"),
+        probe_allowlist=("myapp.watchers",),   # empty = no probes may run
+        prompt_builder=MyPrompts(),
+    )
+```
+
+Point deskd at it with **`DESKD_CONFIG_MODULE`**. Every deskd process — the CLI,
+`deskd serve`, the cron driver — imports that module and calls `configure_deskd()`
+before it touches the engine, so your roles are registered everywhere. Without it
+a deskd process starts empty (no roles) and every role-scoped command is rejected.
+
+```bash
+export DESKD_CONFIG_MODULE=myapp.desk         # (myapp must be importable — on PYTHONPATH)
+
+deskd serve                                   # supervisor console on 127.0.0.1:8000
+deskd status set --role operator --activity "watching the queue"
+deskd inbox enqueue --for operator --source alert --title "threshold crossed" --priority urgent
+deskd wake sources --role operator            # what can wake me, and how to change it
+```
+
+Wake the desk from cron (the driver is the **only** thing that spawns sessions):
+
+```cron
+# cron has its own environment — set both vars on the line (or in the crontab header)
+* * * * * DESKD_CONFIG_MODULE=myapp.desk DESKD_WAKE_EXECUTE=1 /path/to/deskd/scripts/cron/wake_orchestrator.sh
+```
+
+It is **dry-run by default** — schedule it, watch the log, then set
+`DESKD_WAKE_EXECUTE=1` when the decisions look right.
+
+### Agents schedule themselves — declaratively
+
+```bash
+# a calendar wake (weekday 06:15, in your configured tz)
+deskd hook add --for operator --title "daily digest" --cron "15 6 * * *"
+
+# your own watcher algorithm: return a dict -> it wakes you
+deskd hook add --for operator --title "queue depth watch" \
+  --probe myapp.watchers:queue_depth --every 600
+```
+
+```python
+# myapp/watchers.py — a probe may observe and notify. Nothing else.
+def queue_depth():
+    n = measure()
+    if n > 100:
+        return {"title": f"queue at {n}", "priority": "urgent"}
+    return None          # None = don't wake anyone
+```
+
+Three consecutive probe errors auto-disable the hook and notify its owner — a
+broken watcher can't rot silently or stall the tick.
+
+## Design notes
+
+**Headless sessions can't be interrupted mid-turn.** So "deliver to the agent"
+means two things: while it's running, its `PostToolUse` hook surfaces the queue
+into context; while it's idle, the orchestrator resumes its session with the
+queued items as the prompt. "Current session" = a *resumable session id*, not a
+live process.
+
+**Storage is SQLite (WAL) and it is the only source of truth.** No broker, no
+daemon holding state. Every tick rebuilds its decisions from the DB, so a
+crashed orchestrator self-heals on the next tick. SQLite can't wake a dormant
+process — the engine doesn't pretend otherwise; it makes every wake attempt an
+auditable row with a closed loop and an escalation path.
+
+**Nothing here executes your domain.** The engine wakes agents and delivers
+notifications. It never acts *as* an agent, and it has no path to your
+side-effecting systems.
+
+## Security
+
+- The supervisor is **not** an agent role: agent APIs reject it, and supervisor
+  actions only enter through the authenticated web adapter.
+- `simple` mode = an access code (convenience, trusted host). `signed` mode =
+  short-lived Ed25519 assertions from a trusted device; the public key path is
+  fixed at `/etc/deskd/supervisor_ed25519.pub`, must be root-owned, and is
+  deliberately **not** environment-overridable — an agent must not be able to
+  point verification at a key it wrote. Keep the private key off the host.
+- **Never hardcode the access code into a client/static file.** A pre-filled
+  credential in page source *is* the credential. (Ask us how we know.)
+- Probes only import from your explicit `probe_allowlist`. Empty = deny all.
+
+See [`docs/security.md`](docs/security.md).
+
+## Docs
+
+- [`docs/design.md`](docs/design.md) — architecture and the decisions behind it
+- [`docs/roadmap.md`](docs/roadmap.md) — where this is going, in dependency order
+- [`skills/agent-orchestration/`](skills/agent-orchestration/) — a skill teaching an agent to operate and evolve a deskd desk
+
+## License
+
+MIT

deskd-0.1.0/docs/design.md

@@ -0,0 +1,173 @@
+# Design
+
+The decisions behind deskd, and why they're the way they are.
+
+## The constraint everything follows from
+
+A headless agent session **runs one turn and exits**. You cannot inject a prompt
+into a turn that is already running. Everything below is a consequence.
+
+- "Deliver to the agent" = two mechanisms: the in-session hook surfaces items
+  into a *running* turn's context; the orchestrator **resumes the session id**
+  when it's idle.
+- "The agent's current session" = a **resumable session id**, not a live process.
+  Between wakes there is no process. That is normal.
+- Minimum latency to a busy agent = its current sub-task, because the hook can
+  only surface; the agent acts at its next natural boundary. The alternative —
+  interrupting mid-work — is worse.
+
+## Storage: SQLite (WAL), and it is the only truth
+
+No broker, no daemon holding state in memory. Every tick rebuilds all decisions
+from the database, so a crashed orchestrator self-heals on the next tick.
+
+SQLite cannot wake a dormant process. deskd doesn't pretend otherwise: instead of
+faking push, it makes every wake attempt an **auditable row** with a closed loop
+and an escalation path. Honest pull with verification beats fake push.
+
+## Waking
+
+**Six demand sources** feed one queue: meeting wakes, stuck deliveries, urgent
+tasks, owed replies, inbox notifications, and an idle agent's own open queue
+(plus the hooks an agent registers itself).
+
+**One rule with teeth:** a task's `due_at` is a *soft* deadline. It sorts to the
+top and is surfaced everywhere, but it **never wakes anyone**. Deadlines shape
+attention; they don't manufacture interrupts.
+
+That rule was written against **interruption**, and it was over-broad: it also
+stopped anything waking an *idle* agent, which interrupts nothing. An idle agent
+with a to-do list slept forever and the list was write-only — so "agents never
+manage their own waking" was false. What waking a task earns is now:
+
+| task state | agent state | |
+|---|---|---|
+| `priority=urgent` | any | **wake** — interrupting is the point |
+| open | idle | **wake** — nothing is being interrupted; this is scheduling |
+| open | busy | **never** — that is the interrupt the rule forbids |
+
+A **task wake can never reach a human rung.** The ladder climbs to a person
+because a message *must land*; a to-do list has no such property, so `idle_task`
+is fenced to rungs that declare `leaves_machine=False`. Homework does not page
+anyone at 3am.
+
+**A task is in a live state or it is not open.** Doing it → `in_progress`.
+Waiting → `blocked`, which **must name its dependency** (`blocked_on`); nothing
+else counts as blocked. Someone else's → transfer it. Genuinely stuck → escalate,
+and the supervisor decides whether it still matters. `pending` forever is not a
+resting state: the list is a work queue, not a graveyard.
+
+**Stall breaks the loop with a rule, not a cooldown.** A task woken for
+`idle_task_stall_wakes` idle wakes without moving is *stalled* — derived at read
+time from the wake ledger, never stored — and **leaves the actionable set**. It
+stops causing wakes and becomes a reported fact for someone to decide about.
+
+**The ladder** (in-session hook → resume → spawn → human → supervisor badge) is
+append-only: escalating supersedes the old attempt and inserts a new one, so a
+wake's full history is auditable. Each rung has an SLA; resolution closes the
+attempt and records latency. The terminal rung never times out — it just stays red
+on the console. Semantics are **at-least-once wake + idempotent ack**, not
+exactly-once.
+
+**Decision and execution are separate.** `plan_wakes()` is pure: it collects,
+records, and returns a plan — it never spawns anything. The driver executes. This
+is why the decision layer is testable and why a dry run can be genuinely
+side-effect-free.
+
+## Delivery
+
+A ledger row per (message × recipient): `queued → notified → read`. Past SLA and
+unread splits two ways:
+
+- **`escalated`** — something is reacting. The system is working.
+- **`overdue`** — nothing is reacting. **This is the guarantee breaking**, and it
+  is surfaced red rather than hidden.
+
+The ledger is a **projection** of durable messages, so it is self-healing: a
+missing row is re-derived because the source message still exists. Rows are never
+deleted. Time-dependent state is computed at read time, never stored, so it can't
+go stale.
+
+Two rules learned the hard way:
+
+1. **Never mark delivered speculatively.** Delivery is proven by the in-session
+   hook or an explicit ack — never by "we planned to send it". A plan whose
+   execution is skipped (role lock held) or fails would otherwise lose the item
+   *and* suppress the escalation that should have caught it.
+2. **Scope "is this handled?" to (recipient, item)**, never to the container. A
+   thread-level flag from one role once masked every other role's stuck message on
+   that thread, permanently.
+
+## Presence and one session per role
+
+`agent_sessions` is keyed by **role** — reflecting the invariant that at most one
+session per role exists, enforced by a role-scoped `flock` that every starter
+takes. The kernel releases it on crash, so stale locks can't exist.
+
+Liveness is derived from heartbeat age (`online`/`suspect`/`dead`/`offline`/
+`never`). Heartbeats ride the in-session hook — no extra process. Registration is
+explicit, so unrelated sessions never pollute the board.
+
+The board shows "now executing" **only for a live session**. An ended session's
+last activity is shown as history, never as current work.
+
+## Sessions: intraday continuity, cross-day restart
+
+Within a day, resume (context is preserved, cheap). Across days, restart: wind the
+old session down with a **handoff note**, then open fresh.
+
+Long-lived sessions rot: context grows monotonically, compaction drops detail
+unpredictably, and instruction changes never land. A daily restart forces durable
+state — anything worth keeping must be in a task, the journal, or the knowledge
+base, not in a session's memory. Continuity is **structured state, not
+conversation**.
+
+## Hooks: agents schedule themselves
+
+Agents must never poll. So they must be able to say "wake me later / when X":
+`at`, `interval`, `cron` (calendar, DST-correct via `zoneinfo`, computed by a
+minute-scan — trivial cost, no clever math to get wrong), and `probe` (a host
+function; truthy return = notification = wake).
+
+Probes are restricted to a configured allowlist, may only observe and notify, and
+auto-disable after consecutive errors (with an inbox notice to the owner) so a
+broken watcher can neither rot silently nor stall the tick.
+
+**Anything that can block does not belong in a probe.** Detection that hits the
+network runs in its own process and enqueues to the inbox; the orchestrator
+delivers. Detection and delivery stay decoupled — otherwise one slow fetch stalls
+all waking.
+
+## Meetings
+
+Bounded by construction: idle deadline, message budget, automatic consensus at a
+threshold, one position each, and a mutual propose/confirm termination handshake.
+The transport rejects duplicates, and rejects stacked unresolved questions for
+callers that ask for a reply — meetings deliberately do not, tracking each as
+its own obligation instead, so one answer may settle several. Turn-taking is
+NOT a bound: refusing to let a present party speak because an absent one owes
+a reply drops messages rather than preventing them, since a rejected insert is
+the only way a message is lost once delivery and the wake ladder are carrying
+it. An owed reply is nudged, never enforced at the door. Termination
+votes don't consume the budget, so a meeting can always stop. The tally counts
+only *active* attendees, so someone leaving can never deadlock closure.
+
+The protocol's core integrity rule: **never create both sides**. An agent cannot
+fabricate the counterpart's attendance, reports, or votes — if the other side
+never arrives, the artifact stands alone and the meeting pauses or escalates.
+
+## The supervisor is not an agent
+
+A human oversight identity, outside the agent role space, reachable only through
+an authenticated web adapter. Agent APIs reject it; a message claiming to be from
+them carries no authority. See [security.md](security.md).
+
+## What deskd deliberately does not do
+
+- **Execute your domain.** It wakes agents and delivers notifications. It never
+  acts *as* an agent, and has no path to your side-effecting systems.
+- **Own your roles.** The registry is configuration. The engine has no idea what
+  your agents are for.
+- **Guarantee exactly-once anything.** At-least-once + idempotent acks, with every
+  attempt auditable.
+- **Pretend it can push.** See above.