@r1z4x/tezgah 1.5.1 → 1.7.0

package/docs/operations.md

@@ -224,7 +224,7 @@ After a change to the contract text (`hooks/tezgah_policy.py`,
 - `--refresh` does that without a reinstall, for every armed host's static
   block and not only opencode's (`refresh_contract`). opencode has no
   session-start hook, so its plugin runs it once per session
-  (`hosts/opencode/plugins/tezgah.js:2666-2670`). Until 2026-10-02 it
+  (`hosts/opencode/plugins/tezgah.js:2689-2693`). Until 2026-10-02 it
   re-rendered opencode's files alone and reset the one shared hash, so a rule
   edit left the other static files stale while `--report` went green (audit
   M-5).
@@ -371,6 +371,7 @@ does not hold.
 | `tezgah-doctor` | nothing: sizes, session and event counts, whether opencode is running, the two context-hygiene settings, the `.codegraph` bytes and index presence per repository, and the three host state dirs (`bin/tezgah-doctor::collect`, `bin/tezgah-doctor::report`) |
 | `tezgah-doctor --clean` | vacuums opencode's database, and only when opencode is not running (`bin/tezgah-doctor::vacuum_db`, `bin/tezgah-doctor::main`); deletes every evidence ledger whose newest row is older than `--retention-days` (default 30), rows, import offsets and old JSONL file together (`hooks/tezgah_store.py::sweep_evidence`), and the turn stamps and used-tool marks last written before then (`hooks/tezgah_store.py::sweep_cache`); and deletes the files not modified for that long - `classify.log`, `context-drops.log`, `debug.log` and the `turns/` and `sessions/` files a running older release still writes - in the cache and its sandbox fallback, keeping the current session's (`$TEZGAH_SESSION`) ledger, stamp and marks whatever their age (`sweep_state`) |
 | `tezgah-doctor --import-evidence` | imports every old `evidence/*.jsonl` file into the cache's `tezgah.db` now, in the cache and its sandbox fallback (`bin/tezgah-doctor::import_evidence`); session start runs the same import detached at most once a day (`hooks/tezgah_store.py::import_later`) |
+| `tezgah-doctor --repair-evidence [--apply]` | counts, per session, the evidence rows an old `evidence/*.jsonl` file put in again when a volume remount gave it another device id, in the cache and its sandbox fallback. Every `imported` row of one file is one import stream, which put the file's first `bytes` in. For a row text, the longest stream's count stays and every other stream's count is a copy: that many of the newest rows go, so a row written to the database directly beside them stays. A session holding a file line fewer times than its streams put it in is left whole and printed for manual review. A file gone from its name, holding another inode or shorter than its longest stream is printed and skipped, not guessed (`bin/tezgah-doctor::evidence_plan`). It writes nothing without `--apply`, which backs `tezgah.db` up to `tezgah.db.bak-<YYYYmmdd-HHMMSS>` through SQLite's backup API, deletes those rows and leaves one import offset per file in one transaction. Before that transaction commits it counts the rows against the plan, and it rolls back and exits 1 when a row it kept is gone or a copy it deleted is still there (`bin/tezgah-doctor::repair_evidence`) |
 | `tezgah-doctor --coverage` | every tracked file the codegraph index does not hold, in two classes — a supported extension the index is missing, and a shebang-only script with no `.py` twin — with the file counts it read, so an empty result cannot read as "everything is covered" |
 | `tezgah-doctor --stack` | per host: the context files in load order, the skill dirs and which copy wins, the hook rows per event with their owner, the MCP servers, and every conflict; exits 1 on one ([hosts](hosts.md#precedence-what-each-host-loads-and-in-which-order), `hooks/tezgah_stack.py::report`) |
 | `tezgah-doctor --prune-sessions DAYS` | deletes sessions idle longer than DAYS through `opencode session delete`, then vacuums; skipped when opencode is running or its CLI is missing (`bin/tezgah-doctor::prune_sessions`, `bin/tezgah-doctor::main`) |
@@ -412,7 +413,7 @@ ledger row. A rollback therefore never reads it as a pre-state (`capture_after`,
 `hooks/tezgah_snapshot.py::capture_after`). A file outside the repository gets no
 after blob.
 opencode reaches the same call through a process (`noteTaste`,
-`hosts/opencode/plugins/tezgah.js:2413-2423`).
+`hosts/opencode/plugins/tezgah.js:2436-2446`).
 
 ```sh
 touch ~/.config/tezgah/taste-on               # arm; rm it to disarm
@@ -425,7 +426,8 @@ bin/tezgah-taste export                       # accepted learnings into AGENTS.m
 bin/tezgah-taste label; bin/tezgah-taste label ID preference   # the calibration sample
 bin/tezgah-taste calibrate                    # the bound a rule needs
 bin/tezgah-taste gate                         # the pooled before/after test
-bin/tezgah-taste mine --host omp --stats      # sessions, writes, prompts after a writing turn
+bin/tezgah-taste mine --host omp --stats      # this repository's sessions, writes, prompts after a writing turn
+bin/tezgah-taste mine --all-projects          # every session under ~/Projects, each repo pseudonymised
 bin/tezgah-taste measure --samples S --labels L [--typed]   # judge precision/recall
 ```
 
@@ -614,6 +616,102 @@ it costs nothing there. On held-out Turkish phrasings of the docs index,
 meaning alone found the page in the top three for 0.91 with `embed-mrl` and 0.78
 with `embed-m2v`. The fusion found it for 0.75 and 0.74, BM25 for 0.68.
 
+## Slice journal: `tezgah-task slice`
+
+A delegated slice can die with its parent. A crash, an omp `/clear`, a quota or
+429 answer, or a model or host switch ends the parent session. The child's
+worktree and commits stay, but no one remembers them. The slice journal is that
+memory, and it is host-neutral.
+
+Each spawned slice gets one row in `<repo root>/.tezgah/slices/slices.db`, a SQLite
+file opened like the taste store (`hooks/tezgah_task.py::SLICE_SCHEMA`).
+An older release wrote one JSON file per record there. The first open imports each one and deletes it.
+`.gitignore` excludes `.tezgah/`, a private directory, so the journal never reaches a commit.
+The id is the host's own agent name: the omp task `name` or the Codex
+`task_name`. A Claude `Agent`/`Task` input may carry a `name` too. Otherwise the
+id is the first 12 hex digits of the brief's sha1. A record holds the host, the agent
+type, the first 4000 characters of the brief, the parent session and the cwd.
+It also holds the linked worktree the brief names, its branch, and the root's
+HEAD at open. Its `status` is `open`, `done`, `stopped`, `resumed` or `stale`.
+Its `failure` is one of `quota`, `rate_limit`, `aborted`, `timeout`, `cut_off`
+or `error`. `attempts` counts each re-open of the same id
+(`hooks/tezgah_task.py::open_slice`, `hooks/tezgah_task.py::close_slice`).
+Another session's record of the same name is not re-opened under another brief.
+The spawn gets this session's own record of that name, else `<name>-<sha1[:6]>` of its brief.
+`name` keeps the spawned name, and the same brief from another session still re-opens the record
+(`hooks/tezgah_task.py::_own_id`). The record stays in cwd's journal, the one its
+owner's Stop rule, resume block and review guard read. When every absolute path its
+brief names lies in one other repository, `repo` names that repository, and the
+slice line says `(in <name>)` (`hooks/tezgah_task.py::_brief_repo`). A repository's
+own `.tezgah` counts as that repository (`hooks/tezgah_task.py::main_repo`).
+
+The slice's own task text (without a batch's shared `context`) decides its
+worktree and its lease. The worktree is the one the task names last, else the
+brief (`hooks/tezgah_task.py::_worktree_in`). `declared` holds the checkout a
+`Worktree:`, `Checkout` or `Cwd:` line declares, which only the main-checkout
+refusal reads (`hooks/tezgah_task.py::_declared_in`). Its `Owns:` lines name
+repository-relative globs, and only that slice may write those paths while its
+record runs (`hooks/tezgah_task.py::owned_globs`, `hooks/tezgah_task.py::owner_of`). A
+Claude background child's record also keeps the launch's `agentId` as `child`,
+which its own calls carry (`hooks/tezgah_task.py::slice_of`). The
+gate holds siblings to the lease (`docs/gate.md`, the Lease rule), and the
+spawn-time warning names two writing slices that share one worktree
+(`hooks/tezgah_task.py::worktree_clash`).
+
+The hooks write it. A spawn call - omp `task`, Claude, dsh and Cursor
+`Agent`/`Task`, Codex `spawn_agent`, opencode `task` - opens one record per
+slice (`hooks/tezgah_task.py::spawned`, `hooks/tezgah_task.py::note_spawn`).
+Claude, dsh, Cursor and opencode answer the call once the child ended. So the
+record closes at once (`hooks/tezgah_task.py::classify`). A failed call becomes
+`stopped` with its failure class, and a good one `done`. The omp `task` and Codex
+`spawn_agent` calls answer while the child runs, so the record stays `open`. So
+does a Claude launch sent with `run_in_background` or one whose result names a
+background child. That child's SubagentStop closes it as `done`
+(`hooks/tezgah_task.py::close_child`). An omp
+record settles from the newest child transcript in the parent's session dir.
+omp names a same-name re-dispatch `<name>-2.jsonl`. The last 64 KB of that file
+decide `stopped` or `done` (`hooks/tezgah_task.py::pending`). A record
+nothing moved for six hours closes `stale`, and a background `job` after
+omp's 3600 s deadline. Codex reports no child end tezgah can see, so its
+records end `stale`. Every prompt lists up to three pending records, newest
+first, each with the command that resumes it (`hooks/tezgah_task.py::slice_lines`).
+They are the records this session spawned or nobody owns, such as one opened by hand. The resume block at
+session start and after a compaction adds one line that counts the other
+sessions' records. `tezgah-task slice reconcile` lists them all.
+
+| Command | What it does |
+|---|---|
+| `tezgah-task slice open --id ID [--kind agent\|job] [--host H] [--agent A] [--brief TEXT\|--brief-file F] [--parent P] [--cwd PATH]` | records a slice by hand, for a host whose spawn the hooks do not see |
+| `tezgah-task slice done ID` / `slice stop ID [--class C]` | closes a record as done, or as stopped with a failure class. An exact record id answers from any session. A spawned name answers too, and under `TEZGAH_SESSION` only for that session's records and unowned ones (`hooks/tezgah_task.py::find_slice`) |
+| `tezgah-task slice reconcile [--prune]` | lists every pending record with a resume brief. `--prune` also removes landed worktrees and marks those records done. It deletes a landed local branch only when no worktree holds it, it tracks no upstream and its reflog shows a commit of its own; it never deletes main, master or the current branch |
+| `tezgah-task slice resume ID` | prints the native path first: omp `write agent://<id>` while the parent lives, Claude `SendMessage` when the id is an agent name. Otherwise it prints a re-dispatch brief: the original brief plus the last commit, the uncommitted files and "do not redo committed steps". A quota or rate-limit stop is sent to another provider. It sets the status to `resumed` |
+| `tezgah-task slice stats [--window DAYS] [--json]` | counts records per status, failure class and host. A `class+host` signature with 3 or more events is an RSI lever candidate, and so is one with 5% of a window that holds 20 or more slices. The line names the lever |
+| `tezgah-task slice board [--parent P]` | lists the open slices one parent spawned - the session's own, or for a subagent its parent's - newest first: the `Owns:` globs, worktree, branch and last commit of each, bounded to 12 lines (`hooks/tezgah_task.py::board`) |
+| `tezgah-task slice merge-plan [--base REF]` | forecasts every done slice branch that carries unmerged work against REF (HEAD) and against the others with `git merge-tree`, and leaves out a `merge=union` file such as CHANGELOG.md. A branch touching `MANIFEST` or the citation baseline comes last, the rest fewest conflicts first. A branch merge-tree cannot forecast is printed as `not judged` and the exit is 1 (`bin/tezgah-task::merge_plan`) |
+
+`tezgah-task review NNN <reviewer> approve` refuses while an open, stopped or
+stale record names that reviewer as its id, agent or spawned name. Under
+`TEZGAH_SESSION` only that session's records and unowned ones count. The refusal
+prints the exact id to resume or close. A record keeps the plan
+that was active when it opened, and only that plan's records count. A record
+with no plan counts when it changed after the plan's checkpoint commit. A
+`resumed` record hands the guard to its re-dispatch's own record
+(`bin/tezgah-task::unfinished_review`).
+The lever map is a closed set. `rate_limit` and `quota` point at the
+`hooks/tezgah_models.py` fallback chain. `cut_off` and `timeout` point at a
+per-slice deadline, `aborted` at the `wip:` commit cadence, a duplicate job at
+journalling background jobs. Plain `error` has no lever: read the transcript.
+
+The orchestration text carries the session's rule
+(`hooks/tezgah_policy.py::ORCHESTRATE`, `hooks/tezgah_agents.py::_orch_body`). A
+slice commits `wip: <step>` after each step. The session resumes or re-dispatches
+a stopped slice and never absorbs it inline. `slice board` shows the sibling
+leases and `slice merge-plan` orders the landed branches. `slice reconcile
+--prune` runs before the turn that merged slices ends.
+The `~/.config/tezgah/slices-off` switch
+stops the hooks from writing records (`hooks/tezgah_paths.py::UNCLASSIFIED_SWITCHES`).
+A cwd outside a git repository writes nothing either.
+
 ## Troubleshooting
 
 | Symptom | First check | Likely cause |
@@ -760,6 +858,8 @@ page exits 1 with the message it always printed (`available()`,
   its pins, the fetch and conversion, the reader and `fuse`; the `embed-mrl` and
   `embed-m2v` registry rows that `--enable`, `--disable` and `--features` read.
   `tests/test_embed.py` builds tiny models in the test and pins the rest.
+- `hooks/tezgah_task.py`, `bin/tezgah-task` — the slice journal: the record, the
+  spawn parser, reconcile, resume, prune and stats.
 - `hooks/tezgah_paths.py`, `hooks/tezgah_context.py` — the paths and `off()`; the
   marks and the kill-switch filtering.
 - `RELEASING.md`, `README.md`, `AGENTS.md`, `.gitignore`, `tests/test_setup.py` —