Skip to content

v0.6.0

Choose a tag to compare

@github-actions github-actions released this 13 Oct 17:20
· 61 commits to main since this release
df7dfaa

On the built-in Node coordinator, strict mode no longer lets a session write a file it was just refused a read of, /status and hook messages stop publishing raw session ids and your absolute workspace path, and tracking a * glob can no longer empty a policy file; a Python-backend workspace gets these from agent-coherence releases after 0.14.1. The track and untrack commands escape what the coordinator sends and say why it refused a request, the status, track and untrack commands report refusals by exit code, and the hook client is ready for the caller principal that agent-coherence releases after 0.14.1 issue.

Upgrade note: on the Node backend, GET /status now reports every session's agent_name as null; key on agent_id instead. agent-coherence-untrack now exits 3 when a Python coordinator from a release after 0.14.1 refuses to untrack a strict path, and agent-coherence-status exits 2 when the coordinator's registry is busy; scripts that read these exit codes may need updating. On the Node backend, and on the Python backend with agent-coherence releases after 0.14.1, hook texts that name a peer by id now say agent where they said session (see Changed), so a script or test that matches them literally needs updating. The Node coordinator, and the Python coordinator in agent-coherence releases after 0.14.1, now refuse a track or untrack with HTTP 400 (exit 2) when the policy file is one an earlier unquoted write broke or is not a plain list. Plugin releases 0.3.0 to 0.5.0 (Node backend) wrote, and agent-coherence 0.8.0 through 0.14.1 (Python backend) write, a pattern that starts with * unquoted, which makes the whole file load as no entries: check .coherence/tracked.yaml and ignored.yaml and quote any such entry (- "*.md"). On a Python-backend workspace, agent-coherence 0.14.1 and earlier keep writing such entries, so check again after each track or untrack until you upgrade the library past 0.14.1.

Backend scope: unless an entry says otherwise, a coordinator change below is in the plugin's built-in Node coordinator. A workspace the Python coordinator serves gets its coordinator behavior from the agent-coherence library, whichever plugin version is installed: where an entry says the Python coordinator does the same in agent-coherence releases after 0.14.1, 0.14.1 and earlier keep the old behavior.

Added

  • On a Python-backend workspace the hook client now claims a caller principal and sends it with every hook, so a coordinator that issues principals (agent-coherence releases after 0.14.1) can refuse a request for that session from a client that never claimed it. In those releases the Python coordinator binds a caller principal to a session the first time a client claims it (POST /principal/claim). From then on it refuses a request naming that session without the principal on the routes where an unbound caller could do harm (pre-edit, post-edit and session-stop among them), and refuses a wrong principal on every route. The plugin's Node hook client now takes part. On a session's first hook it writes a random claim nonce to .coherence/caller-principal-<agent id>.nonce, claims the principal with it, stores the principal beside it in a .principal file (both mode 0600), and sends it on every later hook in a Coherence-Caller-Principal header. The file names and formats are the Python hook client's, so both clients share one binding per session. Neither file is removed automatically. The coordinator may refuse the principal, for example after losing its bindings because state.db was removed or restored, or because a claim's answer never arrived. The client then claims again with the same stored nonce, stores what comes back and retries the refused hook once. It never makes a new nonce, so it cannot take over a session another client has claimed. If an interrupted write (a killed client, a full disk) leaves the nonce file empty or incomplete for more than 2 seconds, the client does not overwrite it: it names the file on stderr, and the session runs without a principal until you remove that file by hand while no hook of the session is running. A hook it cannot recover fails open with {} and says why on stderr, and nothing it prints contains the principal, the nonce or the coordinator's own error text. This is not a boundary between local processes: anything running as your OS user can read .coherence/. The Node coordinator issues no principals and ignores the header. The client reads backend=node from server.pid and does not claim, so a Node workspace sends exactly the requests it did before. Against agent-coherence 0.14.1 or earlier, which has no claim route, the client still writes the nonce file, and each hook makes one extra local request that the coordinator answers with 404, then proceeds without the header.

Changed

  • /status no longer publishes a raw session identifier. Each session row carried agent_name as claude-session-<session id>, beside the non-reversible agent_id. The Node coordinator serves no detail=full tier, so the default tier, which rendered it, is the only tier that lists sessions; agent_name is now null, and agent_id and the per-artifact states are unchanged. In agent-coherence releases after 0.14.1, the Python coordinator redacts the same field below its operator tier, so with those releases both backends return null for agent_name below the operator tier; 0.14.1 and earlier still publish it on the Python coordinator's default tier.

  • A hook response names a peer by agent id, and a denial or warning no longer reports a write that did not happen. The last-writer field on stale responses and strict denies carried a peer's raw session id (a subagent's raw id, for a subagent writer), reversed out of the agent id by a lookup that has been removed rather than left unused. The texts that name a peer now say agent where they said session: the strict-mode deny reads was updated by agent <id>, the stale-read warning updated by agent <id>, the edit-collision warning another agent (<id>) and each preemption bullet preempted by agent <id>. When a peer merely took the grant, a denial claimed the artifact "was updated", naming a timestamp for a write that never occurred, and the warn-mode stale-read warning made the same claim. Both now have their own message: the grant was revoked, no new version was committed, and the file is still at the version the session last saw. The deny texts, the stale-read warnings and the edit-collision warning are byte-identical to the Python coordinator's in agent-coherence releases after 0.14.1; the preemption bullets say agent there too, but each backend words them differently. 0.14.1 and earlier keep the session wording.

  • agent-coherence-track and -untrack now say why the coordinator refused a request. A non-2xx answer prints HTTP <status>: <error>, or HTTP <status> when the answer carries no error text, the form the Python console scripts use; a 2xx answer that is not JSON prints coordinator returned a non-JSON response. Both used to print coordinator rejected the request, and both still exit 2. The one exception is the strict-path refusal described under Fixed, which agent-coherence-untrack reports in its own lines and exits 3.

  • The Node coordinator's uuid dependency is updated from 14.0.1 to 14.0.2. The first session after the upgrade installs it together with js-yaml 4.3.2 (see Security).

Fixed

  • A warning that cannot name the other agent no longer prints a broken <unknown placeholder. The stale-read warning, the edit-collision warning and the preemption-notice bullets shortened every identity to eight characters, the <unknown> placeholder included, so it reached the model with its closing bracket cut off: another session (<unknown) has been editing docs/plan.md. In 0.5.0 this happened after every coordinator restart, because those texts printed a session id from a lookup that starts empty in each coordinator process. They now name the peer by agent id, which is stored with the artifact and survives a restart (see the agent-id entry under Changed). The placeholder, still used when no writer is on record, is printed whole, as strict-mode denials already did. The Python coordinator makes the same change in agent-coherence releases after 0.14.1; with 0.14.1 and earlier, a Python-backend workspace still prints <unknown.

  • Stale-read warnings and strict denies now use the version the session actually last read. They inferred it as the current version minus one. After two commits by a peer (v1 to v3), a warning's "you previously saw vN" named v2, a version the session never saw; when a peer only took the grant, the guess made an unchanged file look changed, which is what produced the false "was updated" texts described under Changed. They now use the version recorded when the session last read the file, and fall back to the old guess only when no read is on record: a grant recorded by plugin 0.4.0 or earlier, or a first grant that came from a denied Bash or Grep command. The Python coordinator does the same in agent-coherence releases after 0.14.1.

  • /agent-coherence:status no longer asks for the operator view when it falls back to the Python console script. The command ran agent-coherence-status with no arguments. The shim runs the plugin's Node CLI, which asks for the default tier, but with no node or no built dist/cli_status.js (a Python-backend marketplace install, for one) it runs the library's console script, whose default in agent-coherence 0.14.1 and earlier is the operator tier, requested with the Coherence-Local-Operator: true header; that path printed every session's name, which embeds the raw session id, into the transcript. The command now runs agent-coherence-status --detail minimal, which every agent-coherence release from 0.9.0 accepts and both coordinators answer with the default tier, and the Node CLI accepts --detail minimal too, sending ?detail=minimal without the operator header. With agent-coherence 0.14.1 and earlier the default tier still lists each session as claude-session-<session id>, so on that path the session ids keep reaching the transcript until the library is upgraded; releases after 0.14.1 drop the name below the operator tier and also make the default tier the console script's own default.

  • The Node coordinator's default /status tier no longer publishes the absolute workspace root. Its policy_summary.coordinator_root held the absolute path, and the status command prints the answer verbatim, so $HOME and the directory layout reached the transcript on the Node backend. It now reports ., as the Python coordinator's default tier does for the same key in agent-coherence releases after 0.14.1 (0.14.1 and earlier still publish the absolute root there); the protocol corpus pins it on both backends instead of ignoring policy_summary.

  • agent-coherence-status, -track and -untrack now wait 6 seconds for the coordinator, as the Python console scripts do. They gave up after 5 seconds. In agent-coherence releases after 0.14.1, the Python coordinator's --detail full answer, which this CLI can now request (see below), can take just over 5 seconds on a large workspace when a busy registry frees up late; a 5-second limit would report that as request timeout with exit 2. Hooks keep their 5-second limit.

  • agent-coherence-untrack now exits 3 when the coordinator refuses to untrack a strict path, and says what to do (#177). agent-coherence releases after 0.14.1 refuse to untrack a path .coherence/strict_mode.yaml enforces, answering with reason: untrack_strict_path and a refused list. The Node CLI printed that as coordinator rejected the request with exit 2, the same as any other failure. It now prints one line per refused path naming the strict patterns that enforce it, then says nothing was untracked and that the path stays enforced until its entry is removed from .coherence/strict_mode.yaml and the coordinator restarts, and exits 3, as the Python console script does. Any other refusal still exits 2. The Node coordinator does not refuse yet: on a Node workspace, untracking a strict path still removes it from strict mode.

  • The track and untrack CLIs no longer print coordinator text raw, and the CLIs escape the error text they print. A path or reason in a track or untrack answer went to the terminal as it arrived, so an escape sequence could drive the terminal, a bidi control could reorder the line, and a newline could forge a second line. Those strings, the message of a failed request and the refusal text the CLIs now print (see Changed) are escaped the way the Python console scripts escape them in agent-coherence releases after 0.14.1, and a rejected or refused path is quoted the way those scripts quote it. When a shim falls back to the Python console script (no node, or no built CLI), agent-coherence 0.14.1 and earlier still print all of this raw. The Node untrack CLI also prints the coordinator's rejected entries, which the Python untrack script does not. agent-coherence-status still prints the /status body as JSON, which escapes C0 control characters (U+0000 to U+001F) but not DEL, C1 controls, bidi controls or line separators.

  • The track and untrack CLIs now reject an answer of the wrong shape instead of reporting success. An answer whose added (track) or removed (untrack) was not a list of paths, or whose rejected was not a list of objects, was ignored or printed element by element as paths, and the CLI exited 0. It now prints unexpected <endpoint> answer shape and exits 2, as the Python track script does in agent-coherence releases after 0.14.1 (the Python untrack script checks only removed). agent-coherence-track also warns when a path it tracked does not exist on disk yet, as the Python script does.

  • agent-coherence-status now exits 2 when the answer carries no session or artifact lists. When the coordinator's registry is busy, agent-coherence releases after 0.14.1 answer /status with degraded: true and no tracked_artifacts or sessions list. The Node CLI printed that body and exited 0, so a script reading the exit code took it for a workspace with nothing tracked. It still prints the body, then says the registry is busy and to try again shortly, and exits 2; any other answer missing those lists exits 2 with unexpected /status shape. --detail metrics, which carries no lists, is unaffected.

  • The status, track and untrack command docs are updated. /agent-coherence:status says what the default tier it requests carries on each backend and library version, and what the "no coordinator" and "registry busy" messages mean; /agent-coherence:untrack explains exit 3; /agent-coherence:track no longer refers to an internal build step.

  • The README, PRIVACY.md, SECURITY.md, the bug-report template and the plugin's description are corrected (#165). PRIVACY.md and the bug-report template no longer call the default /status tier safe to paste. They say what each tier carries on each backend: only the metrics tier is free of paths, process ids and session identifiers; the Python coordinator reports its process id at the default and full tiers, and 0.14.1 also reports the absolute workspace root and raw session ids there; the Node coordinator reports no process id at any tier. PRIVACY.md and SECURITY.md no longer claim the plugin makes no outbound requests: installing the Node backend's dependencies fetches packages from your npm registry and better-sqlite3's prebuilt binary from GitHub. That install runs on the first session, after each plugin upgrade, after a switch to another Node major version or when the installed native addon fails to load, and on the session after a failed install. The README now says that:

    • an Edit or Write gets no stale-read line;
    • Stop releases committed (MODIFIED) grants as well as EXCLUSIVE ones, so a session's first read of a file it wrote in an earlier turn is reported stale;
    • a strict-mode deny is cleared by a Bash or Grep read run twice, not by a Read.

    It also lists the caller-principal files, the Python-library version each behavior needs, and five new known limitations: the caller principal's trust boundary, untracking a strict path on the Node backend, deny text that points the agent at the Read tool, policy files an earlier release broke, and cross-backend parity that covers the hook decision envelope but not GET /status, GET /health or preemption-notice prose. Its parity claims now name that envelope instead of every surface. SECURITY.md now says what uuid is used for. The plugin's description now says it warns when a session reads a tracked artifact another session has updated, not when a session is about to act on one.

  • The --self-test refusal no longer tells you to switch the workspace to the Python backend. The bundled Node CLI rejects agent-coherence-status --self-test with exit 2, and the message offered printf 'python\n' > .coherence/coordinator_backend as one way to run it. On a workspace whose .coherence/state.db the Node coordinator created, that leaves no coordinator at all: the dispatcher honors the file verbatim, the Python coordinator fails closed on the Node ledger (CrossRuntimeSchemaError), and once the Node process exits every hook fails open with {}. agent-coherence-coordinator --prepare-for-migration is not a way around it: against a running Node coordinator it gets HTTP 404 and exits 2, because the Node coordinator serves no /admin/prepare-for-migration route; with none running it exits 0 without touching the store, and the Python coordinator still refuses it. The message now says the flag needs the Python library's console script, run by its install path (the plugin's agent-coherence-status shim prefers the Node CLI whenever node is on PATH), on a workspace the Python coordinator serves. It also says why: the self-test finishes by checking counters only the Python coordinator serves, so run against the Node coordinator it passes all four steps and still exits 3. On a Node workspace the message points at plain agent-coherence-status instead, as the README already does. The exit code is unchanged.

  • No plugin message or doc tells you to switch a workspace's store to the other backend any more, because nothing can. Each coordinator fails closed on a state.db the other created, in both directions, and agent-coherence-coordinator --prepare-for-migration drains and stops a running Python coordinator without converting anything; the Python coordinator still refuses a Node-created store afterwards, and the Node coordinator a Python-created one. Two Node-bootstrap refusals (an unsupported Node major, and a build that produced no dist/coordinator.js) printed echo python > .coherence/coordinator_backend unconditionally; on a Node-created store that leaves the workspace with no coordinator. They now offer it only while the workspace has no state.db, where the Python coordinator creates its own; with a store present they say to select Python only if the Python coordinator created it. The Node coordinator's CrossRuntimeSchemaError no longer refers to "the supported migration path" for moving a Python store to Node; it says no tool converts a store, and still says never to delete it. The README no longer recommends --prepare-for-migration as a way to switch backends (the binaries table, Selecting the backend, and the Architecture section), and Installing §B no longer says to opt an existing workspace into Node with printf 'node\n', which on a Python-created store leaves it with no coordinator; it now says an existing Python store cannot move. Selecting the backend also warns that an explicit choice on a workspace with a store must name the backend that created it. The Python coordinator's matching message is corrected in agent-coherence releases after 0.14.1; in 0.14.1 and earlier it still calls --prepare-for-migration the supported backend-switch path, and 0.14.1's --prepare-for-migration --help says to run it before switching backends.

  • agent-coherence-status --detail full can read the Python coordinator's operator tier. The Node CLI requested ?detail=full without the Coherence-Local-Operator: true opt-in header, so the Python coordinator answered 403 and the CLI printed "coordinator rejected the request" and exited 2, although 0.3.1 listed --detail full as honored. The CLI now sends the header for --detail full only; the default and --detail metrics requests are unchanged. A refusal now prints HTTP <status>: <error> (or HTTP <status> when the body carries no error), as track and untrack do, and a 2xx answer that is not JSON prints "coordinator returned a non-JSON response" instead of "coordinator rejected the request"; both still exit 2. The Node coordinator's 501 for --detail full, which the CLI now relays, used to say only that detail=full was not implemented; it now says the operator tier is served by the Python coordinator only. It deliberately names no backend switch: a store the Node coordinator created is one the Python coordinator fails closed on, and agent-coherence-coordinator --prepare-for-migration does not convert it.

  • A coordinator answer cut off mid-body is now an error, not a silent success. The CLIs' HTTP request waited only for the response's end event, which never fires when the connection drops after the headers, so the request never settled and agent-coherence-status, -track and -untrack exited 0 with no output; a script read that as an empty success, and track or untrack as a confirmed change. An incomplete response now rejects as the network error it is: the CLIs print "coordinator closed the connection before the response was complete" and exit 2, and a hook fails open with {} (it used to exit with no output).

  • A policy file with long runs of blank lines no longer stalls the coordinator on every track or untrack that adds an entry. The writer trimmed the file's trailing newlines with a /\n+$/ replace, which backtracks over every run of newlines in the file and is quadratic in its length: 60,000 blank lines inside a list (well under the 64 KB cap) blocked the coordinator's only event loop for about 2.3 seconds per call. The trim is now a linear scan with the same result, 5 ms on the same file.

  • On the Node coordinator, tracking or untracking a pattern that starts with * no longer silently drops every other entry in the file (#178). /policy/track and /policy/untrack wrote each entry to tracked.yaml / ignored.yaml as a YAML plain scalar, - ${p}, and a plain scalar is not literal. A leading * is an alias, so untracking *.log stopped ignored.yaml parsing; the loader then fell back to no entries, every earlier ignore stopped applying, and the request still answered success. Several other leading characters (! [ { | % @ ` and quotes) break the file the same way; &, #, key: value and values such as null, 123 or true silently drop the one entry; and # mid-path quietly turned docs/x #1.md into the pattern docs/x. Entries are now written as double-quoted scalars through js-yaml's own dumper, so every one reads back as exactly the string that was sent; the dumper also writes a raw NEL (U+0085, which path validation admits) as \N, which PyYAML would otherwise fold to a space when the Python backend reads the same file. Existing lines are left as they are. The writer now also refuses, writing nothing and answering 400, whenever an append could not take effect: a file an earlier unquoted write already broke (it loads as no entries, so the new entry never would either), a file that holds something other than a list, a valid list in a layout an appended line would break (a [ ... ] list, an indented list or a ... end marker, where the write used to erase entries that were working), and a file it cannot read (which it used to treat as empty and replace with only the new entries). The message names the file, says where the parser stopped, and says how to rewrite it; agent-coherence-track and -untrack print it as HTTP 400: <error>. The Python coordinator writes the same double-quoted form and refuses the same files with 400 in agent-coherence releases after 0.14.1, which fix the identical defect (cohexa-ai/agent-coherence#284). 0.14.1 and earlier still write unquoted entries, append to a file they can read in these cases, and answer 500 for one they cannot.

  • A session that only read a file is no longer told its EXCLUSIVE grant was revoked (#163). The Node coordinator queued a preemption notice for every peer it invalidated, readers included, at three sites: a peer's pre-edit, commit and CAS commit. So a session that had merely read a/plan.md was told "Your EXCLUSIVE grant on this artifact was silently revoked" as soon as another session edited it, a grant it never held. Those false notices also crowded out real ones: a session that read four files and held one write grant saw three of the reads in its next notice block, with the one grant it actually lost pushed behind "Plus 2 more" until a later hook. Of those three sites, the Python coordinator sends a notice only on pre-edit, and only to a peer that held EXCLUSIVE or MODIFIED; Node now does the same: a commit or CAS commit can only invalidate readers (one requires the caller to hold the write grant, the other refuses while any peer holds one), so they queue none. Readers are still invalidated and still get the stale-read warning on their next read of the changed file; only the misleading notice is gone. It also closes the strict-mode path to the same-second rename described in the entry below about a notice naming a session that no longer held the grant; the registry's >= guard stays.

  • A strict-mode denial now names the file it denied, whatever characters the path contains (#164). The deny text was built with chained replaceAll / replace calls that passed the path as a replacement string, and a replacement string is not literal: $& inserts the matched placeholder, $$ collapses to $, and $` / $' splice the surrounding template into the path. The chain also re-scanned what it had just inserted, so a path containing {last_writer_short} or {last_writer_ts_iso} took that value while the real placeholder shipped unexpanded. docs/a$&b.md was reported to the model as docs/a{path}b.md, a path it would then go and re-read. The deny text, and the new grant-change deny text (see Changed), now render in a single pass that inserts each value once and never re-reads it, exactly as Python's str.format does. Only permissionDecisionReason was ever wrong: the decision, and the coordinator state after it, were unaffected. A test asserts Python's exact bytes for every affected token on both texts, with controls ($1, routes/$id.tsx, a path containing {path}) that already rendered correctly and must keep doing so.

  • Strict mode no longer lets a session write a file it was just refused a read of. A strict-mode deny of a Bash or Grep read re-grants the session's read so that the retry the deny invites can run, and records nothing as read, because the denied command never ran. The strict check on Edit and Write looked only for a session the coordinator had invalidated, so that re-granted read also admitted the session's next edit: a whole-file Write from the copy it read before a peer's commit then overwrote the commit, with nothing denied after the shell read (cohexa-ai/agent-coherence#275). An Edit or Write of a strict path is now denied while the session's last read of it is older than its current version; re-running the Bash command or reading the file with Read records the current version and lifts it. After a Grep deny, retrying the Grep does not lift it, because a Grep lists files rather than showing them; a Read or a Bash command that reads the file does. A session that has never read the file at all is still treated like a first-time editor. The Python coordinator does the same in agent-coherence releases after 0.14.1; with 0.14.1 and earlier, a Python-backend workspace can still lose a peer's commit this way. Pinned by three protocol-corpus fixtures that both backends run.

  • A Bash or Grep command denied in strict mode no longer counts as a read. When pre-bash or pre-grep finds a stale tracked file, it re-grants the session SHARED. It does this in strict mode too: the deny fires once, and a retry goes through. That grant also recorded the file's current version as the session's last_observed_version, even though a denied command never runs. After a compaction, the re-grounding stale flag then stayed silent for a file the session had never read at its current version. The same false baseline would have made a grant-change message (see Changed) tell the session that no new version had been committed since a version it had in fact been refused. The grant is now issued after the deny decision, and it records the observation only when the command will run. That holds for every file the command named, including warn-only ones in a denied command, and for a first-seen file registered by a denied command. The grant itself is unchanged. An allowed command still records the read, because it does read the current bytes. So does the retry the deny invites: a session that already holds the grant and reads the file again, through a retried Bash command or a Read, now has the current version recorded as seen. Without that, a strict session that recovered this way kept its baseline from before the deny, or none at all on a first touch, so a later grant handover was reported as a write it had already read and a first-touch file lost its post-compaction stale flag. A Grep is not credited for a file the session already holds: it names every tracked file under its root, not what it showed, so the baseline stays behind until a Read or a Bash command that reads the file. The Python coordinator changes identically in agent-coherence releases after 0.14.1, and the protocol corpus pins both directions on both backends.

  • The admit-path preemption drain is bounded, so a pile-up no longer pushes additionalContext past what Claude Code delivers. Every tracked-file admit hook removed an agent's entire pending-notice queue and rendered one bullet per notice, uncapped: before this change, 80 pending notices with 60-character paths composed about 11 KB, over the 10,000-byte ceiling. Above that ceiling Claude Code does not truncate; it saves the text to a file and hands the model a 2,000-byte preview plus a path, so the coherence notice becomes a pointer the model has to go and open. Each admit hook now removes and renders only the three newest notices, reports the true pending total in the intro, and leaves the rest queued, so the line saying they are still queued is true rather than printed over rows that were just deleted; a long backlog surfaces three notices per tracked-file operation. The composed size no longer grows with the number of pending notices. The bound is on the count, not on path length; a test pins that the payload still fits the ceiling at 1,000-character paths. Because notice timestamps are whole seconds, which of several notices from the same second render first can differ from run to run; nothing is lost, and the choice is among simultaneous events. The Python coordinator bounds its drain the same way, with the same limit of 3, in agent-coherence releases after 0.14.1; 0.14.1 and earlier remove the whole queue and render three, so the notices they do not show are lost.

  • A failed provisioning install now reports what actually failed, instead of blaming your Node version. When npm install fails, bin/ensure-coordinator-node prints a hint. Whatever had happened, it used to say that the No prebuilt binaries found / node-gyp trace above it "means this Node major lacks a better-sqlite3 prebuilt". That trace follows any failure to place the prebuilt binary, a dropped connection included, so a transient network error read as an unsupported Node version: on 2026-09-20 a CI install on Node 24, a supported major, failed this way and passed on a rerun. The install now runs npm at --loglevel=http so the prebuilt download's HTTP status is captured, and the hint names the cause it finds:

    • npm blocked an install script (ESTRICTALLOWSCRIPTS).
    • The prebuilt npm looked for is for a different Node major than the one running: switch Node majors, because a retry will not help.
    • A 404: no prebuilt is published for this platform, architecture or libc, or a mirror or proxy answers 404 for the release host, so a retry is unlikely to help.
    • A 5xx or 429: transient, so retry.
    • Any other status, such as a proxy's 403: a refusal that a retry will not change.
    • No HTTP status was captured: your Node major is fine, but a missing asset and a transient failure cannot be told apart, so try one retry.
    • A connection error such as ECONNRESET: your Node major is fine, and a retry is worth it.

    When it recognises none of these, or could not capture npm's output at all, it says so instead of guessing. npm's per-request lines at that log level are filtered out of what is printed, so a successful install shows the same output as before. The captured log is a temporary file that the script removes when it exits.

  • A preemption notice could name a session that no longer held the grant. upsertPendingNotice guarded its ON CONFLICT DO UPDATE with WHERE excluded.preempted_at_unix_ts > pending_notices.preempted_at_unix_ts — a strict > — while the same function's own docstring promised "latest preempter wins". Those disagree, because the timestamps are whole seconds: two preemptions of the same (victim, artifact) pair inside one second are indistinguishable by time, so the strict comparison declined the second and left the row naming the session it had already replaced. The model then read a bullet attributing the preemption to the wrong peer, which is the operator's only record of who took the grant. Reaching it requires the victim to re-arm a grant without draining its notice queue. When this was found, the strict-mode path did exactly that: pre_bash (and identically pre_grep) re-grants SHARED to suppress repeat fires, then returns the deny before drainNoticeText, and that reader was then queued a second notice. This was twice recorded on #138 as reachable only synthetically; it was reachable over the real hook surface. The fix for #163 in this release stops queueing notices for readers, which closes that path: the end-to-end test through /hooks/pre-edit → strict /hooks/pre-bash → /hooks/pre-edit → /hooks/pre-read now pins that the re-grant earns no second notice, and a registry-level test pins the state transition itself. The guard is now >=, which makes it last-write-wins within a second while still refusing a strictly older timestamp — the only ordering the comparison was ever load-bearing for, and itself pinned by a test. Python's sqlite_registry carries the identical strict > and correctly keeps it: the two backends feed that comparison different clocks. Node stamps Math.floor(Date.now() / 1000), so two preemptions of one pair inside a second tie exactly and the strict form declines the second; Python is handed float time.time(), where two preemptions on separate requests do not collide. So there is no drift to reconcile and nothing to track — the tripwire is the clock, and it is recorded beside the guard itself in the library repo rather than in a ticket, because coarsening those timestamps is the change that would break it.

  • Warn-mode prose no longer promises a surface that cannot answer, and no longer spells timestamps in a dialect the Python coordinator never writes. Three defects on the same model-visible surface. (1) When more preemption notices arrive than session-start renders verbatim, the overflow line reused the artifact template — "run agent-coherence-status for the full picture" — but GET /status carries tracked_artifacts[].path/.version and no notice data at any disclosure tier, so a coalesced notice pointed the model at an endpoint that cannot answer it. The notice block now has its own line saying the rows are still queued and surface on a later tracked-file operation, which is true because session-start reads the queue without removing anything from it. (2) selectPendingNoticesForAgent had no ORDER BY, so rows came back in artifact_id order — and artifact ids are random UUIDs, uncorrelated with preemption time. Harmless only while every caller drains and renders the whole queue; it now sorts newest-first, the order the Python coordinator's notice prose uses, which is the prerequisite any bounded consume needs to delete the same set it rendered. (3) Every stale-read warning, edit-collision warning and preemption bullet formatted instants with Date.toISOString() (…T12:00:00.000Z) while the strict-deny path alone used the module's own pythonIsoUtc, which reproduces datetime.isoformat() (…T12:00:00+00:00) — so the highest-volume prose on the admit path byte-diverged from the canonical backend on every timestamp it printed. The cross-backend protocol corpus could not see this: its harness normalizes both spellings to the same <TS> placeholder. Verified instead by differential comparison against real Python across six instants (zero-fraction, .5, microsecond, .999999), byte-identical in every case.

Security

  • The coordinator's YAML parser is updated to js-yaml 4.3.2, fixing a high-severity CPU-exhaustion advisory (GHSA-2883-xcg3-v3hh). The Node coordinator parses .coherence/tracked.yaml, ignored.yaml and strict_mode.yaml with js-yaml, and those files can be committed to a repository you clone. In 4.3.1, merge keys with empty sources did not count toward the parser's merge limit, so a crafted policy file could keep the coordinator's only event loop busy. v0.5.0 locked 4.3.1; this release locks 4.3.2, and the first session after the upgrade reinstalls it.

  • The policy writer no longer follows a symlink planted at its temporary-file path (CWE-59). /policy/track and /policy/untrack wrote the new policy to a fixed .coherence/tracked.yaml.tmp (or ignored.yaml.tmp) with a plain write, which follows a symlink, then renamed it over the policy file. A repository that committed that path as a symlink had the link's target overwritten with the policy contents on the next track or untrack, and the policy file itself replaced by the link. The writer now uses a per-write random name created exclusively (O_CREAT|O_EXCL), the pattern the caller-principal store already uses, and removes it if the rename fails. Present since the Node writer was introduced.

Internal

  • docs/RELEASE.md matches the live repository settings and puts the version bump in the release PR. The release branch is cut from dev and carries the manifest bump, the lockfile and the promoted changelog, so CI runs on the bumped tree and main never holds a release's code under the previous version. A new step replaces the generated GitHub Release body with the version's changelog section. The doc no longer says main's review requirement lives in classic branch protection (it lives in the protect-main ruleset), that nothing verifies that ruleset (the readiness check does), that the release build job runs the tests (CI on the release PR does), or that the readiness check prints six lines (it prints seven), and the documented tag ruleset now includes the creation rule that limits release tags to admins.

  • A daily check reports when dev's lockfile falls behind main's. Dependabot raises security alerts and PRs against the default branch only, so a fix that lands on main reaches dev only through a forward-merge, and nothing alerts on that step. A lockfile-drift workflow runs tools/check_lockfile_drift.js daily, on pushes to main and dev, and on demand. The daily run is the one that matters, because pushes made by dependabot-automerge.yml with GITHUB_TOKEN start no workflow runs. The check compares the two branch tips per package and major version, using both the lowest and highest installed copy, so it catches a stale copy nested under another dependency and a bump that crosses a major version. An unreadable lockfile fails the check rather than passing it. The check blocks nothing and is not part of the release preflight, because a release tag points at main. The workflow has run from main since 2026-09-16.

  • Dependabot version updates target dev again, and main's merges flow back to dev automatically. Commit 3a1d0ca (2026-07-17) pointed version updates at the default branch on the premise that dev mirrored main. It has not since: dev runs ahead between releases, so Dependabot bumps landed on main first and reached dev only through hand-made forward-merges: six so far (#109, #112, #141, #147, #160, #182), four of them carrying Dependabot bumps. .github/dependabot.yml sets target-branch: "dev" on both ecosystems, so version bumps land on the integration branch and reach main with the release; that takes away no human review, because what merges unattended is decided by dependabot-automerge.yml's gate on either branch, and it keeps unreviewed bumps off main, which unpinned marketplace installs track. What still lands on main by platform design (Dependabot security updates, including transitive fixes that a version update never produces) and by process (the release merge and bump, hot-fixes) is merged into dev by a new forward-merge-main workflow, on push to main and four times a day. It acts as a GitHub App rather than GITHUB_TOKEN, because GITHUB_TOKEN cannot push changes to .github/workflows/, gets its PRs' checks held for approval, and fires no push workflows. The App's key lives in a forward-merge environment that only main may deploy from, because the App can approve PRs and dev takes unreviewed merges; the workflow ignores fork PRs that reuse its branch name, pins every merge to the commit it pushed, and runs no actions/checkout beside the key. docs/RELEASE.md §1 has the one-time App and environment setup, and §2 and §3 now point at the workflow. A conflict fails the run red for a hand merge rather than being resolved. dependabot-automerge.yml now auto-merges npm devDependency patch/minor bumps only: GitHub Actions bumps are third-party code that runs inside workflows holding write tokens or the App key, so each waits for a human (none had ever auto-merged in practice, because GitHub refuses auto-merge with that token on a PR that edits a workflow). Its comments no longer claim a squash-only main or an approval setting that is off.