ppkit 0.2.1__tar.gz → 0.2.3__tar.gz

ppkit-0.2.3/CHANGELOG.md

@@ -0,0 +1,755 @@
+# Changelog
+
+## v0.2.3
+
+`pp memory` is a new command for a memory that agents share: it ranks the
+notes for a situation, follows and proposes links, drafts groups, checks the
+index, and runs an agent's own edit while no other edit runs. `pp queue`
+adds job keys, events, resizes, card pins and retries that take changes,
+and its help is a short page with four topic pages. `pp http` serves under a
+proxy's path, keeps pinned tabs, answers sooner and searches the tabs.
+`pp kill` asks first when a number is also a job's id.
+
+`pp memory` is a new command for a memory that agents share: a folder of
+markdown notes, one fact per file, with `[[links]]` between them.
+
+- `pp memory find WORDS` ranks the notes for a situation by BM25 over their
+  words. Links bring in the notes the words miss, through personalized
+  PageRank, each marked `via` the note it came through.
+- A pointer, `§G:NAME`, is the link to write: one rare character, the
+  memory's scope (`[memory] scope`, `G` by default) and the note's name. A
+  pointer of another scope, such as `§pp:NAME` or a project's `§P:`, is
+  left alone. `check` reports a `§G:` pointer to no note as broken.
+  `[[NAME]]` and markdown links to `.md` files are links too.
+- `pp memory related NAME` shows what a note links and what links it, the
+  notes most like it that it does not link, and the hubs that hold it or
+  might.
+- `pp memory groups` drafts about √N groups for N notes, for the hub notes
+  that `MEMORY.md` lists. `--in HUB` drafts groups for one hub's notes.
+- `pp memory check` lists links to no file, two notes with one name, notes
+  nothing links, notes the root does not reach in two steps, and pairs of
+  notes alike enough to compare. It prints the sizes against √N. Its exit
+  status is 1 only for a broken link or a name two notes share.
+- `pp memory edit -- CMD` runs an agent's own command that changes notes,
+  such as `sed -i` or a python heredoc, under the memory's write lock, so
+  two edits at once take turns. The command finds the memory in
+  `PP_MEMORY_DIR`. The edit is the command's whole session: what the command
+  leaves running is ended with it. When the command fails, leaves something
+  running, runs past `--timeout` (a minute, `[memory] edit_timeout`) or is
+  stopped (Ctrl-C, SIGTERM or SIGHUP), every note it changed, added or
+  removed is put back. `--json` names them. An edit or import that an edit's
+  command runs is part of that edit, and those take turns among themselves.
+- A memory whose folder is a git repository of its own keeps a history:
+  each kept edit and import is one commit of its `*.md` files, named for
+  the notes it changed, with the command, the project and the session in
+  its message. What changed outside `pp memory edit` since the last commit
+  is committed first, on its own. An undone edit commits nothing. `--json`
+  of edit and import gains `commit` and `outside_commit`.
+- `pp memory check` lists the open tasks in notes (unchecked boxes, TODO
+  and FIXME lines, "next step:" lines): a memory holds what is true, and what
+  is to do belongs in a to-do list.
+- `pp memory edit` runs its command with no input where pp has none to hand
+  on, instead of failing.
+- `pp memory import FOLDER...` copies notes in, with `origin:` in their
+  front matter. It never writes over a file, and it lists a name that is
+  taken by other text instead of copying it.
+- Every verb has `--json` and `--dir`. `[memory] dir`, `root` and
+  `edit_timeout` go in `config.toml`.
+
+`pp queue`: a job's session is what a stop reaches, and what its command
+leaves running ends with it.
+
+- A kill or a timeout signals every process in the job's session, not only
+  its process group. A command that moves itself to a group of its own,
+  such as GNU `timeout`, no longer outlives the job. Only a process that
+  starts a session of its own (setsid) leaves it.
+- When a job's command ends and something it started still runs in its
+  session, pp ends that the way a stop ends a job: SIGTERM, the grace, then
+  SIGKILL. The job is recorded with its command's own outcome once nothing
+  of it is left, and its slot, counters and card stay held until then,
+  or until pp's SIGKILL for what it left has had its grace.
+- `--keep-leftovers`, or `keep_leftovers = true` in a project's `[queue]`
+  or in `[queue.NAME]`, keeps what a command that ended on its own leaves
+  running. A kill or a timeout still reaches it. `--no-keep-leftovers`
+  ends it for one job whose project keeps it.
+- A job's `stop` gains `leftovers`, set on pp's own stop for what a command
+  left. Its `by` is "leftovers". A job record gains `keep_leftovers`.
+- A job record's file begins with its state. A listing reads the records it
+  does not hand out no further than that, so ended jobs cost a worker's pass
+  and `status` little. A record an earlier pp wrote is read whole until a
+  pass that writes its queue's records writes it again in the new order,
+  with nothing else changed.
+- A worker's launch pass reads its queued jobs again in one pass, not one
+  look per job. It decides on a read every reader shares whether anything
+  starts, and takes the store alone only when something does.
+- `pp queue` reads whole only the jobs it shows. A record's head carries its
+  priority beside its state and end, which the counts and the run order
+  need. `--json` still lists every live job whole.
+- A built-in command named exactly runs without reading every command file,
+  so every `pp NAME` starts sooner.
+
+`pp http` can sit behind a proxy that serves it under a path.
+
+- `--prefix /notes`, or `[http] prefix`, puts the path before every link,
+  redirect and fetch pp writes. A request is answered with the path or
+  without it, so the proxy may strip it or pass it on.
+- `--bind unix:PATH`, or `[http] bind = "unix:PATH"`, listens on a unix
+  socket. The socket is made 0660, so its group and its folder decide who
+  connects. A socket left by a server that is gone is replaced. A live
+  one, or any other file, is refused. A request on the socket gets the
+  same Host check as one on a loopback port.
+- Every answer says `Cache-Control: no-store` and `CDN-Cache-Control:
+  no-store`, so no cache on the way keeps a copy.
+- `/raw/` serves scripts and stylesheets as `text/plain`, and any other
+  binary file as `application/octet-stream`. Only media keep their own
+  type. HTML and XML keep their sandbox whatever bytes they hold.
+- Each library pp loads from cdnjs is pinned by its SRI hash, and the
+  loader refuses a file it has no hash for. The page's
+  Content-Security-Policy names each library file, and the folder of
+  highlight.js languages, instead of all of cdnjs.
+- `.credentials*` joins the files pp never serves.
+
+`pp http` searches the tabs: the box at the top of every page.
+
+- `/search?q=WORDS` lists the files whose text or path holds every word,
+  each a plain substring in any case, those named for them first, then the
+  newest. Each comes with how many of its lines hold the rarest of the
+  words, counted up to 16, and up to 3 of those lines, those holding the
+  most words first, linked to the line. It reads the first 8 words and says so when it is given
+  more. `/_pp/search` gives the same as JSON.
+- A markdown page opened at a line shows its source, where the line is.
+- It reads only what the tabs serve, through the walk Recent takes, so a
+  hidden, excluded or denied file is never read, nor a link unless
+  `follow_symlinks` is on, when it reads what the file views serve.
+- A search reads no file. The walk reads the text of each file that
+  changed, for up to `scan_budget` CPU seconds, and leaves the rest to the
+  next walk. A search answers from that text, so a change is found once a
+  walk has read it. The page says how long ago the walk listed the files.
+- A binary file, one over `search_cap` (1 MB), and one past the 256 MB of
+  distinct text search keeps are matched by their path alone, and the page
+  says how many. A text two files share is kept once.
+- It reads prose and Python by default: `*.md *.txt *.rst *.org *.tex
+  *.py`. `search` in `[http]` names other patterns.
+
+`pp http` answers sooner.
+
+- A walk lists a folder again only when its mtime has changed. A folder
+  changed in the last two seconds is listed again either way.
+- The Recent walk and the search walk run when the server starts. A request
+  that comes before they end waits for them.
+- The deny list and the globs are matched as one pattern each, and a path
+  is resolved by the kernel in one call.
+
+`pp http` keeps the tabs you pin in its bar.
+
+- "▾ all N" at the end of the bar lists every tab, with a filter box and a
+  pin toggle. A pinned tab stays in the bar, and its handle drags it into
+  the order you want, by mouse or by finger. The pins are kept by your
+  browser, so the server still only reads. With no pins the bar holds
+  every tab, as before.
+- A folder page's headings sort it: click name, size or modified, and click
+  the same heading again for the other way round. Folders stay first.
+
+`pp queue resize` changes what a job reserves: `pp queue resize 14 --gpu-gb
+16`. It takes `--gpu-gb`, `--cpu`, `--mem-gb` and `--need NAME=N`.
+
+- A queued or held job takes any size a pool holds, from its next start.
+  A size a retry of it could not get is refused, as at `add`.
+- A running job can only give back what it reserves. The room is free at
+  once, so a job waiting for it starts. The run keeps what it was started
+  with, such as its cards and `PP_QUEUE_MEM_GB`.
+- A retry of it, and `retry`, reserve what it reserved before the resize.
+  `show --json` and `status --json` gain `asked`, which holds that.
+
+`pp queue`: a job says where it has got to with a line of its output that
+begins `pp-event:`.
+
+- `pp queue` shows a running job's latest event in place of its last log
+  line, and a recent job's beneath its row. `status --json` gives it as
+  `event` on each running and recent job.
+- `show` names each attempt's latest event, and the values its events
+  state as NAME=NUMBER words, such as `peak_gpu_gb=13.2`. `show --json`
+  gives them as `event` and `values`, on the job and on each history
+  entry.
+- `wait -f` prints each event as it comes. `wait ID --event REGEX` returns
+  0 once each job's current attempt has stated an event the pattern
+  matches, 1 where a job failed first, and 4 where one ended well without
+  stating it.
+- Events are read from the job's own part of its log, so a container's
+  output carries them with no mount, and a retry starts with none of the
+  attempt before it.
+
+`pp queue log` and `show` read a job's own part of a log file several jobs
+write.
+
+- A job's lines run from the line pp writes before each attempt to the
+  next such line, or to the end of the file. pp records where the log
+  ended once the run is over, as `log_end` on the record and on each
+  history entry. What lands after that and before the next attempt, such
+  as a stop command's output, is still the attempt's.
+- `log` without -f printed the file's last lines, whoever wrote them, so
+  a file a lane's jobs share showed the latest job's lines under any id.
+  `log -f` read on past the job's end. `show` and a failure's tail could
+  show the next job's lines, and `status` the next job's last line.
+- The line pp writes when it requeues a job now names the job, so it
+  counts as that job's.
+- Jobs that write one file at the same time still mix their lines in it.
+  So can the jobs of two queues that write it one after the other.
+
+`pp kill N` asks first when N is also the id of a queued, held or running
+`pp queue` job.
+
+- Job ids and pids are both small numbers, so `pp kill 14366` meant for a
+  job could signal an unrelated process with that pid at once. Such a pid
+  now shows and asks as a pattern does, and names `pp queue kill`. A
+  number that is no process but is any job's id says the same.
+
+`pp queue add --retry-gpu-gb N`: every retry reserves at least N GB of a
+card.
+
+- `--retries` with `--retry-if "CUDA out of memory"` retried at the size
+  the run had run out at, which failed again. The requeue now writes the
+  larger size on the record with the attempt, and the retry waits for room
+  that size.
+- It is a key too, `retry_gpu_gb`, in a project's `[queue]` and in
+  `[queue.NAME]`. Given as the flag it needs a `--gpu-gb`, and a size no
+  card holds is refused at add.
+- Each history entry now carries the `needs` its attempt reserved, and
+  `show` names them.
+
+`pp queue` hands a job's `--mem-gb` to it as `PP_QUEUE_MEM_GB`.
+
+- It is in the job's environment and in its runner's env file, and unset
+  where the job declared none. The help's docker runner turns it into
+  `--memory` and `--memory-swap`, so a container is capped at the RAM its
+  job reserved.
+
+Smaller changes to `pp queue`:
+
+- Every verb takes selections separated by commas, as `--after` does:
+  `wait 41,42`. A word that holds nothing but commas is refused.
+- `--gpu-gb 0` says that a job that needs no card leaves the flag out.
+- The help says a container sees only what its runner mounts.
+- The help's docker runner copies as printed. Its first line carried a
+  comment, which the kernel hands bash as the name of a script to run.
+- `log -f` on a queued job says it waits for the job to start, and that no
+  worker is up when none is. `drop` of an ended job names `clean`.
+- `pp help queue` is a short page, and `pp help queue containers`,
+  `settings`, `agents` and `reference` hold the rest. `pp help queue all`
+  prints every page.
+
+`pp queue add --key KEY` queues a job once, however many times it is added.
+
+- An add whose key a job in the store carries already adds nothing. It
+  prints that job's id on stdout, as an add does, and says so on stderr.
+  So an agent that runs an add again after losing its answer, or two
+  sessions that add one key at once, queue one job.
+- The key is read in the transaction that stores the job. A key takes the
+  characters a tag takes, selects nothing, and is free again once `drop`
+  or `clean` removes its job. `retry` queues a job with no key.
+- `show --json` and `status --json` gain `key`, null where none was given.
+
+`pp queue`: the next job no longer starts beside work a lost run left.
+
+- A runner's work outside the job's group, such as a container, outlives
+  a run that ends with no exit code of its own: the docker client was
+  killed, or pp's SIGKILL came at the end of the grace. pp recorded such a
+  job and let go of its slot, counters and card at once, and the
+  project's stop command ran after that. So the next job of a lane, or of
+  a shared counter, could start beside that container until the command
+  had ended it.
+- What the attempt held now stays held until that stop command has
+  returned, and `pp queue status` counts it. A worker that dies before
+  starting the command leaves it to the next pass of any queue's worker,
+  which runs it once.
+
+`pp queue clean` keeps a job whose hook has not run yet.
+
+- A worker that dies between a job's outcome and its hook leaves the hook
+  to the next worker. A `clean` before that worker came removed the record,
+  and the hook never ran. Such a record now stays, and clean says which
+  ones it kept and how to run their hooks.
+
+`pp queue`: a stop command that ends its job at once is still that stop's
+outcome.
+
+- pp read a stop's time from a finer clock than the one the system stamps
+  an exit code's file with. That clock moves in ticks of 1 to 10 ms, so a
+  code written within one tick after a stop began going out could read as
+  written before it. Such a job was recorded as its own failure, exit code
+  137, and its `on_fail` hook ran. A timeout's stop in that window was
+  recorded as the job's own failure instead of a timeout.
+- A stop's `going`, `sent` and `kill9` are now read from the clock the
+  system stamps files with. An exit code written in the same tick as
+  `going` counts as written after it, and its code is kept.
+
+`pp queue wait --fail-fast` returns at the first failure.
+
+- A wait or a watch over a batch hears of a job that fails in seconds then,
+  and not when the batch's last job ends. It tells that outcome as it tells
+  any, exits 1, and leaves the jobs still to end running. Over named jobs a
+  drop counts as a failure too. `--idle` takes it as well.
+- A wait that gives up at its `--timeout` tells first how each job that
+  ended has ended, as a watch does as it goes. It used to say only how many
+  had not ended, so a bounded wait in a loop never heard of a failure.
+- A wait or a watch over a queued job whose queue launches nothing, because
+  `config.toml` is wrong or left empty, says so once, with the file and why.
+- The line `add` ends with names one command, `pp queue wait IDS`, with
+  `--fail-fast` for several jobs, and `release` for held ones.
+- `wait --mine` tells every failure this session has not heard of and the
+  latest 20 successes, and counts the rest, which later waits tell.
+
+`pp queue --mine` shows only the queues that hold this session's jobs.
+
+- With `--mine`, `--here` or `--project` the text view leaves out a queue
+  none of whose jobs it would list. `--json` still lists every queue.
+- `pp queue ID` shows that job, as `pp queue show ID` does. `pp queue status
+  ID` says to use show, exit 2.
+
+`pp queue add --ok-rc 12,13`: exit codes besides 0 that count as success.
+
+- A job whose command ends with a code it names is done: `on_done` fires,
+  `wait` exits 0 and `--after` treats it as any ended job. The code is kept
+  on the record, so a model checker's counterexample (rc 13) is done with
+  rc 13. 0 always counts. A command a signal ended exits 128 and the
+  signal's number, so `--ok-rc 137` would count a SIGKILL as done.
+- `ok_rc` in a project's `[queue]` or in `[queue.NAME]` sets it for every
+  job, as every per-job flag's key does.
+- `--ok-rc 10 --ok-rc 20` is both codes, as `--ok-rc 10,20` is. A campaign
+  file's line that gives its own replaces the add's.
+- `show` and the line `add` prints name the codes.
+- A job record gains `ok_rc`, `[]` where none was given.
+
+`pp queue wait -f` follows jobs, from where this session's last follow got to.
+
+- `pp queue watch` is `wait -f`: one verb, with one set of flags.
+
+- A monitor that runs `watch` is ended after a while and started again. The
+  next watch of the same session says every event of a job since the last
+  one it heard, and how each attempt that ended in between ended, where it
+  used to say only where the job had got to. A watch ended in the middle of
+  a pass may say that pass's lines again. A watch of another session, or
+  of none, starts where the job is, as before. A monitor process that is
+  itself started again is a new session unless `PP_SESSION` or the agent's
+  own session names it.
+- pp keeps, on each job, where the follows of its last 8 sessions got to.
+  It writes a position when an attempt starts, every 30 seconds and as the
+  follow ends, so a follow killed outright may say its last lines again.
+  That field is pp's own and no reader is promised its shape.
+
+`pp queue`: a job's stated peak is on its outcome line, and an add well
+past a kin job's peak says so.
+
+- A job whose events state `peak_gpu_gb`, `peak_mem_gb` or `peak_cpu` has
+  that beside what it reserved on the line `wait` and `watch` tell its
+  outcome on: `peak gpu_gb 16.2/32`.
+- An add that reserves well past the peak the newest done job of its
+  family stated says so on stderr, in one line naming every job of the add
+  it covers, with the `resize` that gives room back while they run. A
+  family is one tag, or tags that differ only after their last dot.
+
+`pp queue retry` runs ended jobs again as they ran, or with changes.
+
+- `pp queue retry 12-14 -- --eval-ckpt last` queues each of them again with
+  one argument more. The flags `add` takes for a job's settings are taken
+  too, and win over what the job ran with, `--env` and `--need` key by key.
+- Each new job runs in its job's directory and queue, with its tag, runner
+  and stop, and every setting it ran with, read off its record. It reserves
+  what the job asked before a resize, and records `retry_of`.
+- A job a range, a tag or a prefix names that cannot be queued again (its
+  directory is gone, no pool holds it) is left as it is and named, and a
+  retry that queued none exits 2. One named by its id refuses the retry,
+  and nothing is queued.
+- A retry of a `sh -c` job with words added warns that the shell reads the
+  first word as `$0`.
+
+`pp queue add --card N` pins a job's `--gpu-gb` to card N.
+
+- The job reserves on that card alone and waits for it, though another
+  card has room, so the arms of a timing comparison run on one card.
+- A pin keeps no other job off its card. `card = 1` in `[queue.NAME]`
+  sends a queue's jobs to card 1, and `slots = 1` in its resources runs
+  them one at a time. A job of another queue may still take that card.
+- A card pp does not see, `--card` on a job with no `--gpu-gb`, and a
+  size the card cannot hold are refused at `add` and at `resize`.
+- A job record gains `card`, null where the job may take any card. `show`
+  and the line `add` prints name it.
+
+`pp help queue` says how to read the past and run a host tool.
+
+- `pp queue --json -n N` is a history: `recent` holds the N jobs that
+  ended latest, each with its tag, rc, started, ended and seconds.
+- `--no-runner` runs one tool of this machine's, java for one, in a
+  project whose runner is a container.
+- A `--no-runner` job that starts a container itself hands it its card with
+  `docker run --gpus device=$CUDA_VISIBLE_DEVICES -e CUDA_VISIBLE_DEVICES=0`.
+  `--gpus all` shows it every card, and its device 0 may be another job's.
+
+## v0.2.2
+
+`pp queue` records a kill as a kill when the worker sending it dies before
+it records the send. Such a job no longer ends as its own failure, and its
+`on_fail` hook does not run. A stop's new `going` field says when pp began
+sending it.
+
+`pp queue`: a kill whose worker dies while sending it is still a kill.
+
+- A worker that died between sending a kill's stop and recording it left the
+  next worker to read the job's end as the job's own. That job was recorded
+  as its own failure, with exit code 137 or reason `lost`, and its `on_fail`
+  hook ran. It is now recorded `killed`, and no hook runs. A timeout's stop
+  in the same window now ends as a timeout.
+- A stop gains `going` in `show --json` and `status --json`: when pp began
+  sending it, recorded before anything goes out. An exit code the attempt
+  wrote after that time is the stop's outcome, with the code kept, unless pp
+  was refused the stop. A job that ends on its own just as its worker dies
+  before sending is recorded the same way.
+- `show` says "sending began" for a stop pp began sending and has nothing
+  marked sent for. A stop pp was refused still says "nothing signalled".
+- `kill` reports a job that ended in that window as killed, "ended as its
+  stop was being sent", instead of saying the job had already ended.
+
+## v0.2.1
+
+pp finds the session that runs it with nothing set, so `--mine` works for
+any agent and in a terminal. `pp queue` reads the cards with a command of
+yours, and any command answers to an alias of your own. A `pp-NAME` program
+is a command only in pp's own folders, and no longer on your `PATH`.
+
+`pp`: a program named `pp-NAME` on your `PATH` is no longer a command.
+
+- pp looks for such a program in `~/.config/pp/commands/`, in each plugin
+  and in each `PP_PATH` folder, and reads no `PATH` for one. Other software
+  installs programs named `pp-*`, and on `PATH` such a program takes a
+  command's name or a unique prefix of it (`pp q`) and shows in `pp -h`. A
+  program of yours stays a command by moving it into
+  `~/.config/pp/commands/`, or by listing the folder it is in in `PP_PATH`.
+- Every Python command is still found before any such program, and the
+  programs in that folder order, so nothing pp found in those folders
+  moves.
+
+`pp queue`: the card reading and the calling session are named by you, with
+nvidia-smi and the process pp runs under as the defaults.
+
+- `[resources] gpu_gb = { probe = "CMD" }` reads the machine's cards with a
+  command of yours instead of nvidia-smi. CMD prints one line a card,
+  `index,name,total_MiB,used_MiB,util`, which is nvidia-smi's own
+  `--format=csv,noheader,nounits` line, and the index it prints is the one pp
+  reserves and publishes in `CUDA_VISIBLE_DEVICES`. The reading is cached for
+  the pool's `every` and taken under the probe's own claim, as any probe's is.
+  A probe in a `[queue.NAME.resources] gpu_gb` is still refused: one machine
+  has one set of cards.
+- `pp queue status --json` gains `cards_why`: why `cards` is null, and `""`
+  where the cards were read.
+- pp finds the calling session from the process it runs under: the nearest
+  process above pp that is neither a shell nor a wrapper, named with its pid,
+  its start time and this boot. So `--mine` and a job's `owner` are any
+  agent's with nothing set, since every command an agent runs is a child of
+  the agent's own process, and a person's terminal is a session the same way.
+  `PP_SESSION`, where it is set and not empty, is the name an agent gives its
+  own session instead, and wins over `CLAUDE_CODE_SESSION_ID`. A process pp
+  started itself, a job or its runner or a hook or a stop command, is no
+  session. pid 1 and an init are no session either, so a `wait` left running
+  by a shell that has returned, which the kernel reparents to an init, says
+  there is none instead of answering for another session's jobs. The session
+  is found once in a run, so such a wait reports the outcomes it selected to
+  the session that queued them and no later `wait --mine` of that session
+  reports them again. pp strips those variables from everything it starts.
+- `pp queue status --mine`, which `pp queue --mine` and `ls --mine` are too,
+  is the jobs this session queued, in every state, in the text view and in
+  `--json`'s `running`, `queued`, `held` and `recent`. It applies together
+  with `--here` and `--project`, and narrows the jobs shown and not what the
+  queues, the workers and the pools hold. Where there is no session it exits
+  2, as `wait --mine` does.
+
+`pp`: a command answers to a name of your own.
+
+- `[alias]` in `~/.config/pp/config.toml` names any command anything on this
+  machine: `st = "promote status"`, or a list of words. A word is resolved
+  as a command's own name, then `[alias]`, then a module's `ALIASES`, then a
+  unique prefix, so an alias hides no command and beats a prefix. `pp help
+  st` and `pp st <TAB>` follow the expansion.
+- An alias runs no other alias. One whose key is a command's name or `help`,
+  or outside `[a-z][a-z0-9_-]*`, or whose first word names no command, is
+  skipped and listed under `pp -h`'s "broken (skipped)". The table is read
+  only where a word is not a command's exact name, so a config file that
+  cannot be parsed leaves every command pp ships working.
+- `pp cmd alias` lists every alias of both kinds, with what it runs and
+  where it is declared (`--json` for the same as data). `pp cmd alias NAME
+  CMD [ARGS...]` adds one, `pp cmd alias NAME --rm` takes it back, and `-n`
+  prints the change and writes nothing. Those flags count wherever they
+  stand, so `pp cmd alias st promote status -n` is a dry run. A command line
+  of its own `-n`, `--rm` or `--json` goes after a `--`: `pp cmd alias dq --
+  queue drop -n`.
+- `pp cmd alias` is the one place pp writes `config.toml`: one line of the
+  `[alias]` table under a lock, the file's mode kept, every other byte as it
+  was. A change it cannot make as one line names the file to edit by hand.
+- `pp cmd ls` shows each command's aliases of both kinds, and its `--json`
+  rows gain `config_aliases` beside `aliases`.
+
+`pp queue`: the views, the plans and the help say more of what pp knows
+about your cards, your queues and your projects.
+
+- `status --json` publishes the gpu_gb pool of each scope in `pools` and
+  `shared`, an entry like every other pool's with one field of its own:
+  `per_card`, that scope's budget on each card of the reading and what its
+  running jobs reserve on that card. The text view shows those numbers card
+  by card. So a job is sized against the smallest budget of every scope its
+  queue draws from before it is queued, instead of being refused first.
+- `pp queue` covers every queue a `[queue.NAME]` table names, beside the
+  queues that hold records and the ones a worker is up for. Such a queue
+  with nothing in it is a section with nothing in it and an entry in
+  `--json`, and reading it creates no directory and no file. "no queues yet"
+  is for a machine with none of the three.
+- `pp queue add` warns on stderr where the job has no runner, no `.pp.toml`
+  is in or above its directory, and a directory directly below is a project
+  whose `[queue]` sets one. The warning names that directory and `--cwd`,
+  once per directory, and the job is queued as it asks.
+- The command `add` hands an agent names the ids it queued as ranges (`wait
+  8-13 20`), which is one word for a campaign of a hundred lines.
+- `clean` and `drop` say in their plan that they remove the records and pp's
+  own files for them, and that a log at a path a `log` pattern or `--log`
+  named stays.
+- The extra run of the project's stop command once a run is over writes to
+  the worker's log instead of the job's log. The stop a kill or a timeout
+  asked for still writes in the job's log.
+- `pp help queue` names the shape of each `--json`: one object with its keys
+  for `status`, one job and its watchers for `show`, and a list of `{queue,
+  pid, how, log, up}` for `worker status`.
+- `pp help queue` says that several selection forms are several words on one
+  verb, that a tag or a prefix selects every job of that name the store
+  holds, an earlier round's ended ones too, and that a campaign line's
+  `--cwd` is that line's own directory and so its project.
+
+## v0.2.0
+
+The interface this minor version keeps. `pp help queue` says what is promised
+and what may change in a patch. `pp queue` stops what a container runner
+started, takes a campaign from a file with one job's flags per line, and runs
+a stage after the one it names.
+
+`pp queue`: a job is named and selected the same way by every verb.
+
+- A job added without `--tag` has no name. Views show its command, and a
+  selection by tag never matches it.
+- A `--tag` is at most 64 characters of letters, digits and `.`, `_`, `-`
+  and `:`. It may not hold `..`, be `.` on its own, or read as an id or a
+  range, because a tag can be part of a log file's name.
+- `counter` is not a queue name, beside `probes` and `watchers`: a queue of
+  that name took the place of the job id counter, and every later `add`
+  failed.
+- Every verb that takes jobs takes the same five forms: an id, a range
+  (`12-15`), a tag matched whole, `--prefix P` (repeatable), and `--all`
+  with `-q NAME`. `--all` without `-q` is a usage error, and a tag or a
+  prefix that names jobs in two queues is an error that lists the ids.
+  `pp queue note` is the exception, and takes one job by its id or by a
+  tag that names one.
+- `pp queue clean` takes a selection as well as `--older AGE`.
+
+`pp queue`: a project says how its work is launched and stopped, so a kill
+and a timeout reach work that is not in the job's process group.
+
+- `[queue] stop` in a project's `.pp.toml`, and `--stop CMD` on `add`:
+  `"group"` where the runner's work stays in the job's own process group,
+  else a shell command that ends it. `pp queue add` is refused in a project
+  that sets `[queue] runner` and no stop, naming both spellings.
+  `--runner CMD` on `add` sets the runner for one job.
+- In a project with a command stop, `pp queue kill` and a `--timeout` run
+  that command in place of the SIGTERM to the job's process group. The
+  grace, the SIGKILL and the sweep of the group are unchanged, so a project
+  with `stop = "group"` behaves as it did. The kill line says which ran, and
+  a stop command that failed is reported with its exit code.
+- A job added with `--no-runner` carries `stop = "group"` whatever its
+  project says.
+- The sweep that runs when a job's run is over also runs the project's stop
+  command, where there is one and the attempt wrote no exit code of its own,
+  and it takes the job's process group with it. So nothing the runner
+  started outlives the attempt that started it, and a leaked process no
+  longer holds a reservation the next job is told it may use.
+- A job and its runner are given `PP_QUEUE_CONTAINER`, a name no other run
+  on the machine has, one per attempt, beginning `pp-<queue>-<id>-`; and
+  `PP_QUEUE_ENVFILE`, the path of a file of `KEY=VALUE` lines readable by
+  its owner alone. That file holds the project's `[queue] env`, the job's
+  `--env`, `CUDA_VISIBLE_DEVICES` where a card was reserved, `PP_QUEUE`,
+  `PP_QUEUE_JOB` and `PP_QUEUE_CONTAINER`, and nothing else of the
+  machine's: no `PATH`, `VIRTUAL_ENV`, `CONDA_PREFIX`, `CONDA_DEFAULT_ENV`
+  or `PP_QUEUE_RCFILE`. The record names it, and it goes with the record.
+- An `--env` value, or a `[queue] env` value, holding a newline is refused,
+  and so is a name holding `=`, NUL or a newline.
+- An exit code an attempt wrote while a stop of it was going out is that
+  stop's outcome, killed or timeout, with the code kept as `rc`.
+- `pp queue kill --grace DUR` takes a duration and overrides the job's own
+  grace for the jobs that kill names.
+
+`pp queue`: a job's output goes where the project says.
+
+- `log` in a project's `[queue]`, and `--log PATH` on `add`: a path with
+  `{tag}` or `{id}` in it, relative to the project root or absolute. Any
+  other placeholder, a path holding `..`, and a relative path that leaves
+  the project root are refused. `{tag}` on a job with no tag is filled in
+  with the job's id.
+- Every attempt appends to that one file, after a `[pp queue]` line naming
+  the job and its command, and several jobs may name one file. The record
+  names the file; `log`, `show`, a failure's tail and `PP_QUEUE_LOG` all
+  read it from there. `drop` and `clean` remove the files pp put in its own
+  store, and never a log at a path you named.
+- `--retry-if` matches from the byte offset where the failed attempt's own
+  output begins, so it no longer matches an earlier attempt's lines or pp's
+  own line.
+
+`pp queue`: a campaign file carries one job's flags per line, and a job can
+wait for the jobs it names.
+
+- A line of a `--from` file is the rest of an `add` command line: its own
+  flags, then `--`, then the command. A flag on the `add` is the default for
+  every line and a line's own flag wins over it; `--env` and `--need` merge
+  key by key. A line that is only a command behaves as before.
+- A line is split into words the way a shell splits them, with quotes and
+  backslashes honoured. A line holding `|`, `&`, `;`, `<`, `>`, `(`, `)`,
+  `` ` `` or `$(` outside quotes is refused with its line number, and so is a
+  line with no `--` whose first word begins with `-`. A file one line of
+  which is refused queues nothing. A command that wants a shell operator
+  passes it quoted: `-- sh -c 'python x.py | grep -v noise'`.
+- `--from FILE` together with a command on the same command line is a usage
+  error, and so is a line that names the queue, the file, `--hold` or
+  `--no-start`, which are the batch's and no line's.
+- `--after SELECTION` on `add`: the job waits until every job that selection
+  named has ended, whatever the outcome. The value is one or more selections
+  separated by commas (`41,42`, `41-66`, `s1_eval,s1_report`), read as the
+  job is added and kept as ids on the record. An id no job has is a usage
+  error and nothing is queued. A job that is waiting is skipped rather than
+  waited for, so it never becomes the head of its queue, and a job whose
+  record is gone counts as ended.
+- `pp queue retry` over a range, a tag, a prefix or `--all` shows a plan and
+  asks, as `kill` and `drop` do; `-n` shows the plan and `-y` does not ask.
+  A job that succeeded has ended, so it suits `retry`. The new job is owned
+  by the session that asked for it, and a priority is set with
+  `pp queue reprio` on the job the retry queued.
+- A bare `pp queue wait` waits for every job that is queued or running
+  instead of returning at the first outcome. It names no held job; a
+  selection that names one waits for it and says so. `--timeout` is honoured
+  whatever `--poll` is, and ids together with `--idle` or `--mine` is a
+  usage error.
+- A worker that adopts a running job takes the offset its output begins at
+  from the job's own run claim, so `--retry-if` reads that attempt's lines
+  and never pp's own line.
+
+`pp queue`: every setting has one declaration, one default and one order of
+its sources.
+
+- Each setting of a job is a key of a project's `.pp.toml [queue]` as well
+  as of `[queue.NAME]`: `timeout`, `retries`, `retry_delay`, `retry_if`,
+  `on_fail`, `on_done`, `prio`, `gpu_gb`, `cpu`, `mem_gb`, `need`, `env`,
+  `log` and `grace`. The first source that gives a setting wins, in this
+  order: `add`'s flag, the project's `[queue]`, the queue's `[queue.NAME]`,
+  the built-in default. `env` and `need` merge key by key.
+- `grace` is one setting of the job: `--grace DUR` on `add`, the `grace`
+  key, the resolved value on the record, and 10s by default. A timeout's
+  stop and a kill of that job both take it.
+- Durations are read one way everywhere: `90s`, `30m`, `2h`, `1d`, a bare
+  number of seconds, `.5` and `1.5h`, and `none` where a setting offers it.
+  An empty value, a value that is not finite and one over 1e9 seconds are
+  refused, in a config key as on a command line.
+- Numbers are bounded: `retries` at most 1000, `retry_delay` at most the
+  one-hour cap, a queue's `poll` longer than 0. A need that is 0, negative
+  or nan is refused.
+- `pp queue work` takes no `--backfill` and no `--poll`: both are keys of
+  `[queue.NAME]`, which the queue's worker re-reads every loop, so they
+  change under running jobs with no restart.
+
+`pp queue`: the store and the machine surface.
+
+- A queue's `FORMAT` is 2. A pp that reads another format refuses the queue
+  where it opens it, naming the format the queue says and the one that pp
+  reads, rather than reading it.
+- The `--json` field `gpu`, an integer, becomes `cards`, a list of card
+  indices; a job that reserved no card has `cards: []`.
+- New `--json` fields: `stop_cmd`, `grace`, `after`, `container`, `envfile`,
+  `log_at`, and `cards`, `container`, `envfile` and `log_at` in each
+  `history` entry. `show --json` carries every promised field on a job in
+  each of the five states: a field the record does not hold yet is null, or
+  an empty list. The two exceptions are `after`, which is there only on a
+  job that names the jobs it waits for, and `stop`, only on a job asked to
+  stop.
+- `pp help queue` is one page: a first job, a project whose work runs in a
+  container in four steps, names and selection, campaign files, the settings
+  table, how a job ends, workers, and what is left to you.
+
+`pp kill`: `--grace DUR` takes a duration in the spelling every duration pp
+takes has. A bare number is still seconds.
+
+`pp promote`, `pp cmd` and `pp http`: plans under `-n`, help by flag, and
+links one target holds.
+
+- `pp -h NAME` and `pp --help NAME` print that command's help, as
+  `pp help NAME` does. `pp -h NAME VERB` prints the verb's.
+- `pp promote rollback`, `pp promote link`, `pp promote init` and
+  `pp cmd new` take `-n`: each one shows its plan and changes nothing.
+- `pp promote` does not take over a link path another target holds: the
+  refusal names that target, and `--force-links` moves the link.
+- `pp promote status --json` has `failed`: the current release's
+  activation failed, or nothing gated it.
+- `pp promote diff --json` has `source_gone`. A target whose project
+  directory is gone exits 1 there, in place of git's error.
+- `pp cmd ls --json` has `aliases`, each command's short names.
+- An unknown key in `[[http.roots]]` or `[[http.discover]]` is a config
+  error naming the file and the key, so a misspelt `marker` stops the
+  server instead of serving every folder under `under`.
+- `pp help http` documents every `[http]` key with its default.
+
+## v0.1.1
+
+Fixes. A few command lines and config values that did harm are refused.
+
+- `pp batch run` refuses a file-name field where a shell would read the
+  name again as code: inside `$( )`, backticks, `${ }`, arithmetic, a
+  `[[ ]]` test, a case pattern, a comment, `eval`, `trap`, a shell's `-c`
+  script, or a template with a heredoc or a function. The message names the
+  spelling that works: `sh -c 'cmd "$1"' sh {}`. Its plan lists every
+  command.
+- A `pp batch rename` that is interrupted leaves a journal of what landed,
+  and `pp batch undo` takes that journal and says so.
+- `pp promote WORD` releases nothing when the word is neither a verb nor a
+  path. It used to release the project in the current directory.
+- A wrong value in `[promote]` is refused, naming the file and the key.
+  `name` must be one path component: `name = ".."` let `gc` remove every
+  release and plugin.
+- `pp promote` keeps the release it flips away from, so the one you rolled
+  back to is still there after the next promote.
+- A socket or fifo in a tree project no longer hangs `pp promote`, and a
+  file pp cannot read is a blocker that offers `exclude`.
+- A hook that leaves a process running no longer holds `pp promote`. Each
+  hook's output is a file beside the run's log.
+- A release that `pp promote gc` cannot remove stays whole, and gc exits 1.
+- `pp queue`: a job that cannot start fails on its own and the rest start.
+  A job whose wrapper is still ending reads running, not lost.
+- `pp queue --json` and `pp queue show --json` give a job's variables by
+  name, with each value `***`.
+- An empty duration such as `--timeout ""` is a usage error, and so is an
+  empty `pp kill` target, which selected every process you own.
+- `pp http` never serves `.git`, serves a file whose name is not UTF-8, and
+  sorts by name when `?sort=` names anything else.
+- pp's messages and the `pp cmd add` and `update` screens escape the text
+  they name. TAB completion runs nothing in a command's name: run
+  `pp completion bash` or `zsh` again to replace a saved script.
+- A command file whose name is not UTF-8 no longer breaks `pp -h`.
+- pp needs Python 3.11.4 or later, which `pp promote` always needed.
+
+## v0.1.0
+
+The first release.
+
+- `pp queue` runs commands later, in named queues, when the GPU memory,
+  CPUs, RAM or counters they ask for are free. Jobs have timeouts, retries
+  for the failures you name, and hooks. Tags and ranges select groups of
+  jobs. A project's `.pp.toml` can run its jobs through a runner, such as a
+  container.
+- `pp queue wait`, `watch` and `wait --mine` tell a person or an agent how
+  jobs ended, with the end of the log for a failure.
+- `pp promote` releases a project from a git commit when its check passes
+  on that copy, and rolls back.
+- `pp kill`, `pp batch` and `pp http` stop processes, rename or convert
+  files, and show project folders in a browser.
+- `pp cmd` writes commands, and adds other people's from git, pinned to the
+  commit you read.
+- Completion for zsh and bash.