@kaisers-io/refs 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,225 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-31
+
+### Changed
+
+- **The skill's version-question flow moved into its own file.** Every question about a
+  dependency's source loads `SKILL.md` and `INVESTIGATE.md` in full, and 30 % of
+  `INVESTIGATE.md` was a block on resolving versions to tags and diffing between them — read
+  on every plain source question, used on almost none of them. It is now `VERSIONS.md`, with a
+  route of its own in `SKILL.md` §5 and a one-line pointer at the end of `INVESTIGATE.md`, so
+  a mis-route costs one extra read rather than a wrong answer.
+
+  Alongside it, a compression pass over what remains: the worker output contract was stated
+  twice and is now stated once, the five clickable-link rules became one normalization, and a
+  handful of sentences that repeated something said a few lines earlier are gone. Nothing
+  behavioural was removed — the capability gate, the trust boundary, the five hard rules and
+  the worker prompt's own safety rules are untouched, and the measured partial-clone cost model
+  (which git commands fetch blobs, and that `git blame` fetches one per visited revision) is
+  refs' own measurement rather than something the term "partial clone" implies, so it stays
+  verbatim.
+
+  A plain source question now loads 20 % less. A version question loads about what it did
+  before, plus one extra file read.
+
+### Added
+
+- **`refs sync` and `refs doctor` now report configuration that has fallen behind its upstream.**
+  A configured package path is only a locator, and upstream can delete or move what sits at it.
+  Until now only `refs resolve` noticed, for the one package an agent happened to route to, and it
+  persisted nothing — so a package deleted upstream could sit wrong in the configuration
+  indefinitely while every other package in the same checkout went uninspected.
+
+  Each successful `refs sync` result now carries a nested `structure: {status, packages}`, probed
+  inside the lock the sync already holds, right after the checkout was updated. Nothing is stored:
+  the answer is reported and thrown away, so there is no drift state that can itself go stale. A
+  removal and a relocation are reported as different findings, because they need opposite repairs —
+  telling an agent to "fix the path" of a package upstream deleted sends it looking for something
+  that is not there. Human output gains indented lines under the affected ref and stays silent when
+  everything resolves; the summary counts and exit code are untouched, since a drifted ref synced
+  perfectly well.
+
+  Only refs that actually sync are probed, which keeps `--stale-only` a genuine no-op — and is why
+  `refs doctor` gains a `config-drift` check as the deliberate "check everything now" counterpart.
+  It takes each ref's lock with a short timeout and reports the ref as busy rather than waiting,
+  writes nothing, and reports `warn` rather than `fail`: the configuration has fallen behind,
+  nothing is broken. `refs list` deliberately stays blind — without stored state it would
+  turn a cheap inventory command into a locking filesystem sweep.
+
+- **`refs resolve` answers in one call what used to take three.** The skill's investigation flow
+  began `resolve` → `sync` → `resolve` **again**, and the third call was not ceremony: package
+  verification had described the checkout as it was _before_ the sync, so reusing that answer meant
+  reporting a path that no longer necessarily held what it claimed. `--sync-if-stale` fetches (or
+  clones) only when the ref is stale or its checkout absent, and everything it reports describes the
+  checkout afterwards. The rule has left the skill and become code.
+
+  It refuses, rather than syncing, when the checkout is `unmanaged` or `unverifiable`. `sync`
+  hard-resets and cleans; running it against a directory whose identity was never established is
+  how a stray clone loses its history. A failing sync fails the command rather than returning a
+  success envelope containing a stale path.
+
+- **`refs resolve --project <dir>` reports the version a project has installed.** The skill used to
+  tell the agent to read the project's lockfile by hand, and nothing in refs touched one — so the
+  deterministic half of every "what changed between my version and a newer one" question was done
+  by the least deterministic component available, against pnpm's peer-qualified keys, aliases,
+  overrides and three vendor-specific formats.
+
+  The answer is read from `node_modules`, walking up in Node's own lookup order, and stops at the
+  first installation slot that exists rather than the first readable manifest — falling through to
+  an ancestor would report a shadowed install Node would not have loaded. There is deliberately no
+  lockfile fallback: a lockfile says what _should_ be installed, `node_modules` says what _is_, and
+  the second is the question. `installed.status` is `found`, `not_materialized`,
+  `unsupported_layout` (Yarn PnP, detected but never loaded — `.pnp.cjs` is project code) or
+  `unverifiable`.
+
+- **`refs resolve --ref <ref>`** scopes a query to one ref's packages. A package name registered by
+  several refs used to be answered with "use the full ref key" — advice the command could not
+  honour, because a full-key query routes by _ref_ and comes back with `package: null`. The error
+  now names a remedy that exists.
+
+- `refs doctor` gained a `locks` check. A held lock used to be invisible: acquisition failed with a
+  message that named no owner, and `doctor` had no lock check at all — so the one command meant to
+  answer "is something stuck?" could not see the thing that was stuck. The check lists every entry
+  in the locks directory with its recorded owner, how long it has been held, and against which
+  window.
+
+  A held lock is **not** a warning by itself: that is what a concurrent `refs sync` looks like, so
+  it reports `ok` with the holder listed. `warn` is reserved for something that will not resolve on
+  its own — a recorded process that is gone, a lock past its window and still there, metadata that
+  cannot be read, or something that is not a lock at all occupying a lock name. Like every other
+  `doctor` warning, it does not change the exit code.
+
+### Changed
+
+- **`refs resolve` establishes that the path it hands back is really this ref's checkout.** It used
+  to report presence from a `.git` entry alone, while `add` and `sync` both ran a stronger guard
+  before mutating — so the one command whose result is read as "the source is here" was the one
+  that did not check what was there. A manual clone at the derived path, a half-finished `remove`,
+  a restored backup or a symlinked second home all produced a confident answer about the wrong
+  repository, with no error and no warning.
+
+  Every reply now carries `checkout: {status, reason?}` — `managed`, `missing`, `unmanaged` or
+  `unverifiable` — read straight out of `.git/config` without spawning git, so the hot path stays
+  subprocess-free. The origin URL is never echoed back in `reason`; it can carry credentials.
+
+  `managed` requires the `core.hooksPath` marker to be **this home's** hooks directory, not merely
+  present — the comparison `add` already makes — so a manual clone that sets it for its own purposes
+  does not pass. A config git itself would reject (an unterminated quote, an undefined escape, a
+  line that is neither a section nor an assignment) is `unverifiable` rather than partially read: a
+  file git would not accept is not evidence of identity.
+
+  **Package verification is gated on it.** A manifest read inside an unrelated checkout can answer
+  `verified` for a package that has nothing to do with the query, so anything other than `managed`
+  or `missing` now yields `package.status: "unverifiable"` instead of a confident location.
+
+  `missing` is unchanged and still means `checkout.status === "missing"`. Callers should branch on
+  `checkout.status`, which answers the question `missing` was often assumed to.
+
+- **The "lock is held" error now says who holds it and for how long.** It used to read `lock <name>
+is held — another refs process is running`, which left no way to tell a running `sync` from
+  something that crashed 90 seconds ago. It now names the recorded pid, whether that pid is still
+  present, how long the lock has been held, and when it becomes reclaimable.
+
+  It deliberately says "recorded pid … is present (identity not verified)" rather than "held by pid
+  …": only `ESRCH` establishes that a process is gone, so a pid that answers may equally be an
+  unrelated process that reused the number. And it says "reclaimable", never "released
+  automatically" — nothing removes a lock in the background; the phrase means the next acquisition
+  attempt is entitled to take it.
+
+- **An operation that ran without the lock it asked for now fails instead of reporting success.**
+  A lock can still be lost while its holder works — a stolen lock is detected by the next renewal,
+  or by release finding a foreign token. Previously the callback's result was returned as if
+  nothing had happened. It is now reported as a `conflict` (exit code 5), because the work ran
+  without the mutual exclusion it requested and its result is not trustworthy. An operation that
+  failed on its own keeps precedence: its own error is what the caller sees.
+
+### Fixed
+
+- The `rm -rf` commands `refs doctor` and `refs add` suggest are now quoted. Ref keys derive from
+  user-supplied urls and permit spaces, `$()`, backticks, semicolons and quotes, and the refs home
+  itself routinely sits under a path containing a space — so pasting an unquoted suggestion could
+  delete several wrong paths and leave the intended one, or execute a command substitution embedded
+  in a repository name. The form is now `rm -rf -- '<path>'`; `--` additionally stops a path
+  beginning with `-` from parsing as options.
+
+- A pid in a lock's metadata is now required to be a positive integer within the range
+  `process.kill` accepts. `0` and negative values are
+  process-_group_ selectors for `process.kill`, so metadata carrying either made the liveness probe
+  answer for a whole group — reporting a long-gone owner as present, and keeping its lock
+  unreclaimable for the rest of its window. A value past that range is worse still: Node rejects it
+  with a `TypeError` rather than an errno, which the probe read as "not gone, therefore present".
+  Such metadata is now reported as malformed instead of acted on.
+
+- A lock is no longer taken away from a holder that is still working, however long the work takes.
+  Locks were judged by a fixed ten-minute age: past it, a waiter treated the lock as abandoned and
+  stole it even when its owner was demonstrably alive and mid-operation. Since the per-ref lock is held across a whole clone or
+  fetch, any repository large enough to take ten minutes could end up with two processes running
+  `checkout -B` / `reset --hard` / `clean -fd` against the same directory.
+
+  A holder now renews a lease while it works, so a lock is abandoned when its process is definitely
+  gone **or** its lease has expired — never merely because the work took a long time. "The pid still
+  exists" does not override an expired lease, which is what keeps a recycled pid from stranding a
+  lock forever.
+
+  The same constant was also too long at the other end: a crashed `sync` or `add` left its lock
+  behind and blocked the ref for the full ten minutes. An abandoned lock is now reclaimable after
+  two minutes rather than ten.
+
+  Two limits are worth knowing. A holder whose event loop is stopped for longer than the lease — a
+  suspended process, a sleeping machine — cannot renew, and is stealable after two minutes where it
+  used to take ten; in practice a sleeping machine suspends every refs process on it, and the
+  pending renewal fires on resume. And a lock written by an older CLI carries no lease and is still
+  judged by the ten-minute rule it was written under, so upgrading never dispossesses a running
+  older process. The reverse does not hold:
+  an older CLI reads no lease, so it can still take a lock from a live current holder once ten
+  minutes pass. Holds longer than that during a rolling upgrade are not protected.
+
+## [0.10.0] - 2026-08-13
+
+### Added
+
+- `refs resolve` now verifies that the package it routes to is actually where the config says
+  it is. A configured `path` is only a locator; the package name is its identity, and upstream
+  repos restructure on their own schedule. Previously a package that had moved — or a different
+  package that had taken over its directory — was handed back regardless, so an agent read the
+  wrong source and answered confidently. That failure produced no error and no warning.
+
+  `package.status` now reports what was established: `verified`, `relocated` (found at exactly
+  one new path, which is returned in place of the stale one), `unmaterialized` (no checkout yet),
+  `unverifiable` (verification could not complete — `reason` says why), `ambiguous` (the name
+  exists at several paths, listed in `candidates`), or `missing`. All six exit `0`; see
+  `docs/commands.md` for the full contract.
+
+  `relocated` corrects the answer for that call only and never writes to `config.toml`. Persist
+  it with `refs edit <ref> --package <name> path <new-path>`.
+
+### Changed
+
+- **`resolve`'s `package.local_path` can now be `null`.** It is `null` for `missing` and
+  `ambiguous`, where no safe location is known. A caller that treated a zero exit as "here is a
+  usable path" must check `package.status` first; previously the field was always a string.
+
+- Workspace detection now reports why it found nothing. An unreadable or malformed workspace
+  declaration, an unreadable manifest, a candidate resolving outside the repo, an unsupported
+  pattern, a package directory reachable only through a symlink — each used to collapse into the
+  same empty result, leaving a transient read error indistinguishable from "every package was
+  removed". Each is now reported, and a scan carrying any of them is treated as possibly
+  incomplete: it can neither conclude that a package is gone nor that a single sighting of one is
+  unique. `refs add` is unaffected — it consumes the same best-effort list it always has.
+
+  A manifest that reads fine but declares no usable `name` is reported too, but does **not** make
+  a scan incomplete: there is demonstrably no resolvable package at that path. Nameless manifests
+  are common enough (zod's own repository root has none) that treating them as failures would
+  permanently suppress detection for those repos.
+
+  One limit is deliberate and worth knowing: a scan only covers what the repo's workspace
+  declaration points at. A package registered by `refs add`'s npm fallback — at `path: "."`, or
+  the packument's `directory` — lives outside that coverage, so if it moves, `resolve` reports
+  `unverifiable` rather than guessing. It never reports `missing` from a scan that had nowhere
+  to look.
+
 ## [0.9.0] - 2026-08-13
 
 ### Added
@@ -470,7 +689,9 @@ trusted-publishing pipeline end to end.
   installed git hooks.
 - Agent skill (`skills/refs/`) documenting the investigate/add/maintain workflows.
 
-[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/kaisers-io/refs/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/kaisers-io/refs/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/kaisers-io/refs/compare/v0.8.3...v0.9.0
 [0.8.3]: https://github.com/kaisers-io/refs/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/kaisers-io/refs/compare/v0.8.1...v0.8.2