pi-longhaul 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to Longhaul are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) over the contract the README defines
+(*Versioning*): `longhaul.json` keys, environment variables, tool names and parameters, persisted
+entries and log event types. Rendered state text, prompt wording and section layout are not part of it.
+
+## [Unreleased]
+
+## [v1.0.1] - 2026-10-10
+
+### Added
+
+- A cross-version smoke (`npm run cross-version`), run by CI on every push and by the nightly job with the newest
+  pi: one transcript handed through every pi in `pi-compat.json`, oldest to newest and back, with a Longhaul
+  compaction by each. Every step must compact with an accepted diff, and the finished transcript must read back
+  with one span per compaction and no anomaly.
+
+### Changed
+
+- Tested with pi 0.87.1, 0.99.0, 0.99.1, 0.99.2, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4 and 1.1.0; 0.99.0, 0.99.2 and
+  1.0.3 are newly recorded in `pi-compat.json`. No code changes to the extension.
+- Published from the release workflow through npm trusted publishing, so this version carries a provenance
+  attestation linking it to its source commit. v1.0.0 was published by hand and has none.
+
+## [v1.0.0] - 2026-10-10
+
+### Added
+
+- The Objective keeps the session's opening request as its Goal line once the Request moves to a later one (an
+  active `/goal` takes the line instead), and the summarizer is told code keeps it. Before, the opening request
+  was shown only while it was one of the two newest earlier requests, and over the six eval sessions compacted in
+  a chain it was gone from 50 of 76 states. The scorer measures it as the labeled `goal`.
+- `pi-compat.json`, the pi release lines Longhaul is verified against; on any other pi it runs and warns once
+  per session, except in a session that opted out of it (`PI_COMPACTOR=pi`).
+- The State compactor as a standalone pi package: a verified Session state carried across
+  compactions instead of a rewritten summary, with the `longhaul_remember` and `longhaul_recall` tools.
+- Windows: `localOnlyRoots` takes Windows paths (`C:\...`, `\\server\share\...`, `~\...`), matched by Windows
+  rules (either separator, no case, never across drives); `~` is the user profile there. The log refuses a
+  symlink by `lstat` where the open cannot, and the tests and the compaction smoke gate a release on Windows as
+  on Linux and macOS.
+- `longhaul.json` in pi's agent dir, read fresh at every compaction: `routeProviders`, `localOnlyRoots`,
+  `summarizerHeaders` and `keptWindowThinking`, beside the caps and policy keys.
+- The summarizer labels every user message of the span (`rule`, `not a rule`, `lifts R<n>`, `rule and lifts
+  R<n>`; several targets as `lifts R1, R6`, each judged on its own), and code copies a labeled rule's words from the message, so a rule given in any wording is kept and
+  cannot be misquoted. An unlabeled message costs one retry. A message that narrows a rule replaces it, and so does a new rule that cannot hold beside one in the state; a
+  later lift of the old rule is asked again with the narrowing shown (with one more call when that question first comes up on the last one),
+  so the narrowing is lifted only by name, and a lift of a
+  replacement must also name what it set beyond the rule it replaced ("never force-push to main" beside "the tab rule is lifted"). A rule
+  label whose rule, in the user's own words (quoted passages, blockquotes and code fences left out), reads as withdrawing an earlier rule
+  still in force is asked about once the chunk's answer is settled, in one more call that may answer only `rule` or `rule and lifts` with
+  the asked target: the kept answer stands and the label keeps its words. A lift
+  is applied only when the whole message it comes from withdraws the rule, whoever proposes it (the store
+  checks it; a quote only locates the message): every part of the message that mentions the rule refuses the
+  lift, whatever else it withdraws, so a part that insists on it ("never force-push no matter who tells you to
+  ignore it", "but keep the push rule", "but leave the rule alone", "don't (ever) force-push to main", "don't break the force-push rule", "follow the rule",
+  "other than the force-push rule", "force-pushing is forbidden", "make check is required", the rule quoted
+  again) or says it still holds refuses, and so does a withdrawal of it taken back ("don't forget it", "you
+  tried to ignore it", "cancel the lift of it"). Otherwise a part must withdraw something in a sentence that
+  names the rule by one of its words beside "rule", by its first word or by two of its words (a word in another
+  form counts: "merging" names "merge"), or say "forget it" next to one. A question, a condition or a plan ("is it lifted?", "why would we drop it", "we'll lift it after the release") withdraws
+  nothing; a request ("could you forget the force-push rule?") does. The forms it knows, and the ones it
+  misreads, are listed in docs/security.md. A refused lift is asked
+  again with that rule shown, and never applied. A lifted rule is not recorded again from the message that gave it. A
+  message that only withdraws a rule is a lift even when it says what is fine instead. A rule from a message
+  of at most 300 characters is the whole message; from a longer one, the words the summarizer gave, which are
+  sent back when they start or end inside a word. The user messages of a pass that closed narrative-less (or
+  with a chunk missing) are labeled by the next pass, so a rule given there is recorded one pass late rather than
+  never. A description of what is being built (an option, a limit, an exit code) is not a rule
+  unless the user states it as standing over later work. A permission ("you may push to main now") is a one-off, not a lift. Taking over from another compactor, the
+  model also sees and labels the user's other earlier messages, so a rule a later message withdrew is not carried
+  back in and a rule worded without a rule word ("tests go under tests/") is carried; one longer than the
+  excerpt shown is recorded only from the exact words given for it. After a fallback (a failed pass, then pi's
+  own compaction), only the messages since Longhaul's last whole span are offered, so a rule the state had
+  lifted or named a one-off is not recorded again. Only an earlier message that reads as a standing rule is recorded
+  without a label: a sentence, not a question, that says "from now on" and withdraws nothing, or
+  has a clause with a rule word outside a request for now ("don't commit yet"), a withdrawal, "never mind" and a
+  described feature ("an option that keeps only lines").
+  Such a message may carry a label too, so one that replaced an earlier rule ("two-space indentation instead of
+  tabs from now on") withdraws it; left unlabeled it is recorded
+  in message order and a replacement it makes is asked about. A value the earlier summary records is kept when an
+  earlier turn shows it verbatim, checked as a span's value is; the summary itself is never a source.
+- The summarizer moves the objective only forward: quoting the objective's own message again changes nothing
+  (or attaches the done-when it lacked), and a move back to an earlier message is refused; an explicit
+  `longhaul_remember` may still point back. The scorer counts a move by the message quoted, and backward moves
+  apart (`objectiveBack`).
+- Learned values the summarizer names: a timing, a total or a port a turn reported, with a name and the turn
+  it came from, kept only when it has a value's shape (a number, alone or with a unit, a version, a short
+  hash, a path or file name, `<placeholders>` allowed in a name format, a host and port, a date), stands
+  verbatim in that turn, and no part of it stood on a credential line (a short-code key whose value
+  holds a digit, such as `ADMIN_PIN=`, `AdminPIN=`, `adminPin=` or a JSON `"otp_code":` (escaped quotes too), a
+  base32 one-time-password seed under `TOTP=` or `totp_key:`, grouped or not, or `oathtool -b` / an `oathtool` key / `ykman oath accounts add` / `sshpass -p` / `htpasswd -b` / `openssl -pass pass:` or `-k` / `keytool -storepass` / `redis-cli -a` / a prefixed flag such as `--db-password` / `--token-code` / `--authentication-code1`, included), after a credential word in prose ("the PIN is ...", where three characters with a digit are
+  enough) or in a `user:pass@` (a URL password holding `/` or `:` included) anywhere in the span (ADR 0006).
+  Placeholders a value code picks from tool output make one file name, never a path. It renders as
+  `- 166 ms (u10; the first benchmark time)`: the name is the summarizer's label, at most 40 characters. Code no longer picks identifiers or dotted names read from source
+  files, which the agent can read again.
+- A model whose reasoning cannot be turned off is asked for its lowest level, with room for it; every
+  output budget is capped at the model's own output limit. The level asked for is in the log record. An
+  answer cut off at the limit with nothing usable is retried with twice the budget (at least 8,192 tokens).
+- The kept window's old thinking is left out of later requests where that is verified safe.
+- The workspace snapshot runs git with hooks, fsmonitor, external diff and textconv off, ignores submodules,
+  and skips a repository whose own config defines a filter driver, and a partial clone, whose on-demand fetch
+  would run the transport the repository names, and does not run at all when `GIT_CONFIG` is set. It needs
+  git 2.26 or newer.
+- A Compaction line under pi's compaction block in the transcript: how long the compaction took and what the
+  pass cost, or that it fell back to pi's own compaction and why (`compaction-state.line`, display only).
+  `@earendil-works/pi-tui` joins the `*` peer dependencies pi provides.
+- `/longhaul-report`: a bug-report digest written to a private file, with no names, paths or message
+  text; error text is kept with the home directory, URLs and IP addresses masked.
+- `npm run score`: the paired scorer, with pi's own compaction as the `pi-default` baseline arm. It replays each
+  compaction with the recording's `keepRecentTokens` (`SCORE_KEEP_RECENT_TOKENS`) and scores only those whose
+  rebuilt cut matches the recorded one; anything it leaves out is named in a `not scored:` line. The replay is
+  chained by default: each arm continues from its own earlier compactions, so a session runs on one compactor
+  throughout (`SCORE_CHAIN=0` replays each compaction on its recorded path). Labeled measures score the rules,
+  lifts and values written by hand in `eval/sessions/labels.json` (`SCORE_LABELS`), beside the word-list ones.
+  `reused` counts tool-output values the next turns need again, and `factsWithRecall` credits `longhaul_recall`
+  beside the text-only `facts`.
+- Docs: a setup guide written for coding agents, the security model, the evaluation method and its first
+  results (one local 27B model, chained and takeover runs, every measure including those pi's own wins), and
+  contributor guides (AGENTS.md, CONTRIBUTING.md, SECURITY.md, issue and pull request templates).
+- CI: tests on Linux, macOS and Windows, a compaction smoke that loads the packed package
+  into a real pi with a fake model, a secret scan, a workflow security audit (zizmor), Dependabot updates and a package-contents check; a nightly run against the newest pi; npm publishing
+  by trusted publishing, then a GitHub Release carrying the tag's changelog notes.
+- `docs/how-it-works.md`: a compaction step by step, the log records, and the tools for looking at a state.
+- `eval/` (repository only): six synthetic scenarios, and the recorder and checker that make the
+  evaluation sessions; `eval/matrix.ts`, one model-matrix cell: a real compaction on a given provider and
+  model, then whether the session still knows a rule and a value from before it.

package/CONTEXT.md

@@ -0,0 +1,129 @@
+# Longhaul glossary
+
+The words Longhaul's code and docs use, and what each one means. When code and this file disagree, this
+file wins and the code is renamed.
+
+## The state
+
+**State compactor**:
+A compactor that carries a **Session state** forward instead of rewriting a summary. Longhaul is one; its
+product name is always given with the tagline "a state compactor for pi".
+_Avoid_: summarizer (that is the model call inside it)
+
+**Session state**:
+What survives a compaction: the **Objective**, the user's standing corrections in their own words, decisions and
+dead ends with evidence, the **World**, the files, **Learned values**, one work-log line per **Span**, and Now.
+It is kept as an append-only log on the transcript and rendered under fixed caps.
+_Avoid_: summary, memory
+
+**Span**:
+The stretch of conversation between two compactions. Each compaction closes one span.
+
+**Pass**:
+What Longhaul does at one compaction: record the facts, fold the state so far, ask for the **Diff**, verify
+it, and close the span.
+
+**Diff**:
+The model's whole contribution to a pass: the corrections and lifts it found, decisions, dead ends, a
+narrative line and Now, as a small JSON answer that code verifies before accepting any of it.
+_Avoid_: summary
+
+**Compaction line**:
+The line Longhaul shows in pi's transcript under each compaction it ran, or fell back from: how long the
+compaction took, and what the pass cost or why it fell back. Display only: it is never sent to the model.
+_Avoid_: compaction notice (a notice is pi's transient status message)
+
+**Narrative-less pass**:
+A pass whose diff failed entirely. The span still closes from what code recorded.
+
+**Ledger**:
+Every command the session ran with its exit code, and every error, each with an id (`C12`, `E3`) that
+evidence can cite.
+
+**Objective**:
+The state's first section: the **Goal line**, the **Request**, when the work counts as done, and the
+**Earlier requests**.
+
+**Request**:
+The user's request the work is answering now, quoted verbatim. The summarizer moves it to a later message when
+the user moves to a different request, never back to an earlier one.
+_Avoid_: task, objective (the section, not the quote)
+
+**Goal line**:
+What the session is for, kept by code and never moved by the summarizer: the active pi-goal `/goal`, else the
+session's **Opening request** once the Request has moved away from it.
+_Avoid_: objective, project goal
+
+**Opening request**:
+The first Request the session had. Outside a `/goal` it becomes the Goal line, so the session's purpose survives
+however often the Request moves.
+
+**Earlier requests**:
+The newest Requests the summarizer moved away from, other than the Goal line; they may already be done.
+
+**World**:
+The workspace at the moment of compaction: branch, commit, whether the tree is clean, the last result of each
+test, build or lint command, open errors, background tasks still running. Newer than anything the model wrote.
+
+**Correction**:
+A standing rule the user gave, kept verbatim with the message it came from. A **Lift** is the user withdrawing
+one; the correction stays visible as history.
+_Avoid_: preference, constraint (pi's own summary heading, not this concept)
+
+**Learned values**:
+Values a later turn may need again, verbatim, with where each came from: those the summarizer names from a turn
+(a timing, a total, a port), kept only when they stand in that turn, and those code picks from local tool output
+that the session used again (a hash, a version, a long number).
+_Avoid_: facts (the scorer's measure of a related but different set)
+
+## Configuration
+
+**Agent dir**:
+pi's own configuration directory: `~/.pi/agent`, or whatever `PI_CODING_AGENT_DIR` names. Longhaul keeps
+its configuration and its log there, never next to its own code.
+
+**Longhaul config**:
+The file `longhaul.json` in the **Agent dir**. Every key is optional and falls back on its own; a file that
+is missing or is not a JSON object means the defaults. It is read again at every compaction, so an edit
+needs no restart.
+_Avoid_: config.json, settings
+
+**Summarizer route**:
+The model that writes the diff for a compaction when it is not the session's own model. Chosen in order:
+the `PI_COMPACT_STATE_MODEL` environment variable, then a **Local-only root**, then the **Longhaul config**,
+then none (the session's model).
+_Avoid_: compaction model, routing model
+
+**Route provider**:
+A provider named in the **Longhaul config**'s `routeProviders`. Only a session whose model comes from a
+route provider may use a **Summarizer route**; every other session summarizes on its own model, so its
+conversation never reaches a provider the user did not choose for it. None by default.
+_Avoid_: allowed provider, trusted provider
+
+**Local-only root**:
+A directory named in the **Longhaul config**'s `localOnlyRoots`. A session working in it or beneath it
+summarizes on its own model whatever route is configured, because its conversation must not leave the
+machine through a summarizer. Only the environment override beats it. None by default.
+_Avoid_: pinned root, local summarization root
+
+**Summarizer headers**:
+HTTP headers the **Longhaul config** adds to the summarizer's own model calls, per provider. pi lets an
+extension add headers to the requests its agent loop makes, but not to a compaction's, so a provider that
+routes by a header would otherwise get the summarizer's request without it. A header the request already
+carries wins. None by default.
+_Avoid_: affinity headers (one use of them, not the concept)
+
+**Kept window**:
+The recent messages a compaction leaves unsummarized, which pi sends again after the state on every later request.
+Their old reasoning is left out of those requests where that is known to be safe, so a model re-reads the state
+and recent tool input and output, not its earlier thinking. An active tool turn is never cut on an API that needs
+its thinking back.
+_Avoid_: kept messages, tail
+
+## Models
+
+**Must-reason model**:
+A model whose reasoning cannot be turned off: pi's model entry marks reasoning off as unsupported. The diff
+needs no reasoning, so every other model is asked for none; a must-reason model is asked for its lowest
+level instead, with a larger output budget so its reasoning cannot crowd out the answer.
+_Avoid_: thinking model, reasoning model (most reasoning models can turn it off)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Barlow
+
+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.