Reports: only write entries with real information; tick: actually retire closed sessions

Reports no longer get an entry for routine mechanical steps (a plain
dispatch, a session closure Marc already asked for, a nudge, a pass
with nothing to triage) -- only for actual findings/decisions/problems.
Zero new entries in a tick run is now the normal case; PROTOCOL.md's
worked example replaced with entries that carry real information
instead of 'dispatched X'/'triaged N items' noise.

TICK.md step 3: a session whose Close diwan session is checked off now
gets genuinely torn down by the tick agent -- herdr tab close on its
DIWAN_ID's tab, :session: tag stripped from the heading, DIWAN_ID
property kept as a historical record. Resolves the 'retired-session
teardown' known gap from DESIGN.md (previously only reported, never
actually closed). Not yet verified against a real live tick run.
This commit is contained in:
marc committed 2026-11-09 18:34:07 +01:00
1 parent c09f2a1a11
commit c7859400a1
3 files changed
+17 -15

No files matched your search

+4 -4
View File
@@ -62,8 +62,8 @@ Note what's *not* here: `last_tick_commit` is deliberately **not** updated by th
**Agent half** (`TICK.md`), five steps, each its own commit:
1. Triage `inbox.org` only (other files changing is someone else's edit): events → `esdeveniments.org`, tasks → wherever they actually belong, `:diwan:` items get moved but not acted on yet, new topics only get a new file when nothing existing fits.
2. Tag consistency: any `:session:`/`:chat:` heading without a `:diwan:` tag on itself or an ancestor gets `:diwan:` added directly to it. Then resolve `:chat:` ownership: chats under a `:session:` ancestor are left for that heading's own session; orphan chats get answered inline if trivial, or escalated (see step 3's three-way decision) if not.
3. Handle every `:diwan:`-tagged heading without an open `:session:`: trivial ones get answered inline, no tag beyond `:diwan:` ever assigned. Non-trivial ones split two ways — self-contained within the heading's own subtree gets a `:session:` tag and `diwan do <file>:<line> --diwan-id <slug>` run *by the tick agent itself* (the tick agent is the only thing that ever originates a fresh `DIWAN_ID`); inherently cross-cutting work (spans multiple files/headings, can't be parallelized — archiving, bulk cleanup, moving things between files) is done by the tick agent *directly*, right there, no session at all, possibly spread across several tick runs if it needs Marc's input first. The same handling applies to any open item under `diwan.org`'s `Tasks` heading — diwan's own self-maintenance backlog, no tag needed there since the location already signals it (see PROTOCOL.md's `diwan.org` section). Already-open sessions (`:session:` tag + `DIWAN_ID` present, `Close diwan session` still `[ ]`) get their subtree's content left alone as always, but are checked for a nudge: if any commit in this tick's change range *not* authored by the diwan git identity touched a line inside that subtree (a hand-authored heading edit, a new unread `:chat:` entry, anything Marc did), the tick agent re-runs `diwan do <file>:<line> --diwan-id <id>` on the existing ID — a continuation dispatch into the session's own tab/agent, not a fresh one — purely to wake it up; no nudge at all if nothing hand-authored touched the subtree. This is the only mechanism that gets a change Marc makes to an active heading in front of its own idle agent — nothing watches the file otherwise.
4. Write one short, titled, checkbox subheading per notable thing this run did into `diwan.org`'s Reports log (not one paragraph for the whole run), each with the title itself linking to the one heading it's about (plain text if there isn't one) and a 1-2 line signed body; delete any already-`[X]` subheadings first.
3. Handle every `:diwan:`-tagged heading without an open `:session:`: trivial ones get answered inline, no tag beyond `:diwan:` ever assigned. Non-trivial ones split two ways — self-contained within the heading's own subtree gets a `:session:` tag and `diwan do <file>:<line> --diwan-id <slug>` run *by the tick agent itself* (the tick agent is the only thing that ever originates a fresh `DIWAN_ID`); inherently cross-cutting work (spans multiple files/headings, can't be parallelized — archiving, bulk cleanup, moving things between files) is done by the tick agent *directly*, right there, no session at all, possibly spread across several tick runs if it needs Marc's input first. The same handling applies to any open item under `diwan.org`'s `Tasks` heading — diwan's own self-maintenance backlog, no tag needed there since the location already signals it (see PROTOCOL.md's `diwan.org` section). Already-open sessions (`:session:` tag + `DIWAN_ID` present, `Close diwan session` still `[ ]`) get their subtree's content left alone as always, but are checked for a nudge: if any commit in this tick's change range *not* authored by the diwan git identity touched a line inside that subtree (a hand-authored heading edit, a new unread `:chat:` entry, anything Marc did), the tick agent re-runs `diwan do <file>:<line> --diwan-id <id>` on the existing ID — a continuation dispatch into the session's own tab/agent, not a fresh one — purely to wake it up; no nudge at all if nothing hand-authored touched the subtree. This is the only mechanism that gets a change Marc makes to an active heading in front of its own idle agent — nothing watches the file otherwise. A session whose `Close diwan session` is already `[X]` gets retired for real: the tick agent looks up its `DIWAN_ID`'s herdr tab and actually closes it (`herdr tab close`), then removes the `:session:` tag from the heading — the `DIWAN_ID` property itself is left in place as a historical record. None of dispatch, nudge, or closure get a Reports entry on their own; see step 4.
4. Delete any already-`[X]` Reports subheadings first, then — only for things that actually clear the "real information" bar, not routine mechanical steps like a bare dispatch or a session closure Marc asked for — write one short, titled, checkbox subheading per reportable thing this run did into `diwan.org`'s Reports log (not one paragraph for the whole run), each with the title itself linking to the one heading it's about (plain text if there isn't one) and a 1-2 line signed body. Zero new entries is a normal outcome.
5. Only if 1–4 all succeeded: update `state.json.last_tick_commit` to current `HEAD` and commit under the diwan identity.
**Verified live** (2026-11-08, herdr 0.9.5 + Claude Code, before both the 2026-11-09 tool/content split and the pi-only harness switch): dispatched for real, ran to completion with zero permission prompts, correctly left two already-open `:session:`-tagged sessions untouched (back when `:session:` was still spelled `:diwan:`, before the tag rename — see "Known gaps" for what's unverified post-rename), correctly found nothing to triage, wrote a proper signed report, and updated `state.json` correctly. A second immediate `diwan tick` correctly no-op'd. **Not yet re-verified with a real dispatched agent** against the current state of things (post-split two-repo layout, `pi` as the sole harness) — path resolution and `pi`'s own startup have each been tested separately (see below and "Known gaps"), but not yet together through a full live tick run. Do that before trusting it for real.
@@ -92,13 +92,13 @@ Same split: `cmd_do` (CLI) decides identity/dispatch mechanics; `DO.md` governs
A `DIWAN_ID` *is* a herdr tab label in the `diwan` workspace, and (while its agent process is alive) also that agent's name. This is why it must satisfy herdr's agent-name rule: `^[a-z][a-z0-9_-]{0,31}$`. `slugify()` enforces this at mint time (lowercase, non-alnum → hyphen, truncated to 24 chars, forced to start with a letter) and `cmd_do` additionally validates *every* `DIWAN_ID` it's about to dispatch — including ones already stored in a heading — against that same regex before touching herdr, erroring out with a clear message rather than letting herdr reject it after the CLI has already created a tab (which used to leave an orphan tab behind; fixed by closing the just-created tab on any `agent start` failure).
Lifecycle: **fresh** (no property) → `diwan do` mints an ID, creates the tab+agent, heading now has `DIWAN_ID` + open (`[ ]`) `Close diwan session` → **active** (any further `tick`/`do` on this heading is a continuation; `tick` explicitly leaves active sessions alone) → Marc checks off `Close diwan session` (`[X]`) → next `tick` notices and retires it (per `TICK.md` step 3 — note: as of this writing the tick procedure only *reports* that a session closed; it does not yet actually call `herdr tab close` on it — see "Known gaps").
Lifecycle: **fresh** (no property) → `diwan do` mints an ID, creates the tab+agent, heading now has `DIWAN_ID` + open (`[ ]`) `Close diwan session` → **active** (any further `tick`/`do` on this heading is a continuation; `tick` explicitly leaves active sessions alone) → Marc checks off `Close diwan session` (`[X]`) → next `tick` actually retires it (per `TICK.md` step 3): closes the herdr tab for real, removes the `:session:` tag, leaves the `DIWAN_ID` property in place as a historical record — **retired** (the heading can still be found later by that `DIWAN_ID`, but there's no live terminal and no tag pointing at one).
## Known gaps / explicit non-goals (don't "fix" these without discussing)
- **Tool/content repo split just happened (2026-11-09), not yet re-verified live.** This repo used to be both diwan's own dev copy *and* a throwaway test-content repo at once; it's now tool-only, with content split out to a sibling `diwan-dev-notes` repo. The CLI was updated to resolve `DIWAN_DIR` (its own install dir, `Path(__file__).resolve().parent`, overridable via the `DIWAN_DIR` env var) separately from `DIWAN_NOTES_DIR` (`git rev-parse --show-toplevel` from the invoking directory by default, overridable via the `DIWAN_NOTES_DIR` env var), and the dispatch prompts now pass `DIWAN_DIR`-absolute paths for `PROTOCOL.md`/`TICK.md`/`DO.md`. This has been syntax-checked and smoke-tested for path resolution (including both env var overrides, from outside any repo), but **not yet run through a full live tick/do pass with a real dispatched agent** against the new two-repo layout — do that before trusting it for real.
- **No flake yet.** The split prepared the ground (tool repo is self-contained, no content-repo assumptions baked into its own files) but there's no `flake.nix` in this repo yet, and the shebang still runs via a bare `nix shell nixpkgs#python3` rather than a proper package. Until that lands, "installed on `PATH`" means manually symlinking/aliasing `diwan` somewhere on `PATH` yourself. `DIWAN_DIR` exists specifically so a future flake's install layout (e.g. docs copied into `$out/share/diwan/` alongside a wrapped binary) can override the default `Path(__file__).resolve().parent` guess if it doesn't hold.
- **Retired-session teardown.** `TICK.md` step 3 says a closed session has "nothing for you to do to the heading's content" and that herdr-side teardown "is not your job" — but nothing else currently closes that tab either. Right now a `Close diwan session` checked off (`[X]`) just... sits there, tab still open. This is a real gap, not yet decided whether the CLI should gain a path for it or whether `TICK.md` should just say to run `herdr tab close` directly.
- **Retired-session teardown is designed but not yet verified live.** `TICK.md` step 3 now has the tick agent actually close the herdr tab (`herdr tab close`) and strip the `:session:` tag once `Close diwan session` is checked off, rather than just reporting that it happened — but no real tick run has exercised this path yet. Worth a close look the first few times it fires: does the tab lookup by `DIWAN_ID` label reliably find the right tab, does tag-stripping leave `:diwan:`/other tags intact, does it behave sanely if the tab was already closed by hand.
- **No real conversation continuity across resumption.** Covered above — intentional for now, but worth revisiting if resumed `do` sessions turn out to need more context than the heading text carries.
- **`pi` is smoke-tested for ad-hoc dispatch, but not yet exercised against real heading content.** `--approve` has been confirmed live for ad-hoc `diwan do` dispatch and continuation, including against a content repo `pi` had never run in before (no trust-dialog block, unlike Claude Code — see "One harness, chosen deliberately" above). Still untested: a real `diwan tick` run, and `diwan do` against a real `<file>:<line>` heading (DIWAN_ID minting, `:chat:` protocol, scope discipline) rather than a free-text ad-hoc prompt.
- **`diwan.org`'s `Config` heading is a placeholder, not wired up.** PROTOCOL.md documents an intended home for configuration values governing diwan's own behavior (tick cadence, tab retention, that kind of thing), but the CLI reads none of it — the env vars (`DIWAN_DIR`, `DIWAN_NOTES_DIR`, `DIWAN_PI_APPROVE`, `DIWAN_MAX_TICK_TABS`) remain the only real knobs. Don't assume anything in that heading does something until the CLI actually reads it.