Skip to content

v0.7.0

Choose a tag to compare

@github-actions github-actions released this 13 Nov 08:54
· 10 commits to main since this release
d4bd31c

On the built-in Node coordinator, a workspace now runs one coordinator, at the repository root, that stops once no client can reach it; a session keeps a read of each file it releases, so it can edit that file again on its next turn; every spelling a disk treats as one file reaches one record; an opted-in pre-edit is refused while another agent holds the file; and /status serves the operator view, so a CoherentVolume with managed globs attaches. On either backend, a session start refuses a .coherence that is or holds a symlink and tells the model, and the plugin's hook client and commands send nothing to a coordinator that has exited. Each entry names the agent-coherence release that brings a change to a Python-backend workspace.

Upgrade note:

  • Restart the Node coordinator. A Node coordinator that plugin 0.6.0 or earlier started keeps serving its workspace after the update, and new sessions join it, so none of the Node coordinator changes below apply until it stops, and it does not stop by itself. From the workspace root, check that ps -p "$(head -n 1 .coherence/server.pid)" -o command= names dist/coordinator.js, run kill "$(head -n 1 .coherence/server.pid)", then start a new session. Do the same with the .coherence/server.pid of any subdirectory or linked worktree an earlier session started a coordinator in (see Fixed).
  • Links in .coherence. A session start now refuses a workspace whose .coherence is a symlink, or holds a symlink, a FIFO, a socket or a device directly inside it, on either backend, and the Node coordinator refuses one too (see Fixed). On the Node backend these links worked before and stop working now: .coherence itself; state.db and its -wal and -shm; hook.secret; strict_mode.yaml; coordinator_backend; tracked.yaml, which worked only until the first track replaced the link with a regular file; and ignored.yaml, likewise until the first untrack. On a Python-backend workspace the session start refuses any such link as well, whichever agent-coherence release is installed, with one exception: a .coherence the session start cannot list, such as one an archive unpacks without read permission, passes for the coordinator to decide. agent-coherence 0.15.0 then makes it listable and reads and writes through any link inside it. Releases after 0.15.0 make it listable and refuse it. To keep the state on another disk, mount a directory at .coherence. Otherwise replace each link with a copy of the file it names, and move state.db together with its -wal and -shm: a copy of state.db alone loses its history without a message. Do this with no coordinator running for the workspace, stopping any as above: one an earlier release started through a link goes on writing where the link pointed while your copy falls behind.
  • Policy patterns. On the Node coordinator a pattern without ** in tracked.yaml, ignored.yaml or strict_mode.yaml now matches as on the Python coordinator and may reach more files: a tracked *.md now tracks every .md file in the workspace (see Changed). An ignored.yaml entry no longer takes a strict path out of strict mode, and an untrack that covers a strict path is refused (exit 3): a workspace that switched strict mode off for a path that way finds it enforced again (see Fixed).
  • server.pid and server.port. A Node coordinator that stops now leaves .coherence/server.pid holding only its pid line, where it deleted the file before, unless it ran without its lock. Do not delete the file yourself. A script that took the file's presence to mean a coordinator runs should look for the port on its second line, and a script that read .coherence/server.port should read that line too: the Node coordinator no longer writes server.port (see Changed). A server.pid written by hand for a process that holds no lock and has no backend=node line no longer counts as a running coordinator, and the status, track and untrack commands exit 2 when the coordinator server.pid names has exited. A Node coordinator now stops within 5 seconds once its server.pid is gone or rewritten, for example when you delete .coherence, and nothing starts another until the next session start, resume, /clear or compaction.
  • Links in tool paths. A Read, Edit or Write through a link that points outside the workspace, or does not resolve, is no longer coordinated, and one through a link inside the workspace is coordinated under the path of the file the link names, so a pattern written against the link's path no longer matches it (see Changed). This is in the plugin's Node hook client, which the hooks run on either backend once a Node-backend session has built it on this machine.
  • Noticeable without action (see each entry):
    • In strict mode a session that holds a file for writing is now denied a read of it after a change made outside the coordinator.
    • A session keeps SHARED on files it released, so /agent-coherence:status lists it there. A session already denied its own file stays denied until it re-reads with a Bash command or a new session starts.
    • On a disk that folds names, the first start merges records an older build split for one file, and an agent that lost its write grant there must read the file again before it commits.
    • /status gains pre_edit_if_unheld, fold_profile, fold_table_unicode and policy_summary.strict_mode_pattern_count, counts a broken policy file as one rejected entry, and answers ?detail=full with 403 or the operator view instead of 501.
    • A store failure on a hook route answers HTTP 200 {"ok": false, "reason": "internal: <ErrorType>"} where some routes answered HTTP 500.

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.15.0, 0.15.0 and earlier keep the old behavior. The session start's .coherence check runs on either backend, and so does the plugin's Node hook client wherever it is installed.

Added

  • On the built-in Node coordinator, a pre-edit that opts in to acquire-or-fail is now refused while another agent holds the file, as on the Python coordinator in agent-coherence releases after 0.15.0 (Cohexa-ai/agent-coherence#246). A pre-edit that sends "if_unheld": true asks for the file only if no other agent holds it. The Node coordinator ignored the field and answered as for any pre-edit: it took the file from its holder, queued the holder a notice and admitted the caller with a collision warning. Now, on a tracked path another agent holds EXCLUSIVE or MODIFIED, it answers {"ok": false, "reason": "other_holder", "holder_agent_id": "<32 lowercase hex>"}, keys in that order, and changes nothing: the holder keeps its grant, and the caller keeps its queued notices. Any agent identity other than the caller's own counts as another agent, so sibling subagents refuse each other, and so do a parent and its subagent; the caller's own repeat is admitted, and a SHARED reader is not a holder. The holder check and the grant run in one SQLite transaction, so no other grant can land between them. An opted-in admit never carries a collision warning. The plugin's own hooks do not send the field. Only a JSON true opts in:

    • a pre-edit that sends no if_unheld, or any other value, answers exactly as before, unless it delivers a reclaim notice (below), and still takes the file from any holder, including one that opted in;
    • on an untracked path, or a held path untracked afterwards, an opted-in pre-edit is admitted with {"ok": true} unchecked, and a stale strict-mode editor still gets the strict deny first;
    • the request needs no caller principal, because the Node coordinator issues none, so a caller that sends the holder's own session id is admitted as the holder's repeat; the Python coordinator in agent-coherence releases after 0.15.0 answers HTTP 400 to an opted-in request without a principal;
    • when .coherence/state.db is busy before the grant, the answer stays {"ok": false, "reason": "internal: SqliteError"} and nothing is granted; when only the delivery of the caller's queued notices after the grant finds it busy, the request is admitted without them and they stay queued.

    An opted-in pre-edit also reclaims a grant another agent has held for 30 minutes or more, counted from that agent's first grant in its continuous hold, even if that agent is still working. The Python coordinator's background sweep reclaims such a grant; the Node coordinator has no sweep, so the opted-in request does. The holder's grant is revoked, the caller is admitted, coordinator.log records one agent-coherence: reclaimed artifact=… line, and the holder's next admitted Read, Edit, Write, Bash or Grep, or its re-grounding after compaction, tells it the grant was reclaimed after being held 30 minutes or more while another agent asked for it, and to read the file again before editing it. The 30 minutes are fixed. Without the reclaim, one crashed or interrupted session could keep a file from opted-in callers indefinitely. The reclaimed holder's next commit of the file is refused with commit_not_allowed. The Python coordinator's refusal starts the same way and also carries reclaimed: true (agent-coherence 0.15.0). The README's Known limitations list what the check does not cover.

Changed

  • On the built-in Node coordinator, /status serves the operator view and advertises the acquire-or-fail refusal, so a CoherentVolume with managed globs attaches, and a fresh read carries its version (#249). The Node coordinator answered GET /status?detail=full with 501, so a CoherentVolume from the agent-coherence library with managed globs could not check that the coordinator enforces them: under on_error="strict" its construction raised, and under "degrade" it ran detached with coherence enforcement off. Now:

    • a ?detail=full request that carries Coherence-Local-Operator: true (the value in any case) is answered with the default tier's body plus four lists in policy_summary: tracked_patterns, user_added_patterns, ignored_patterns and strict_mode_patterns, the patterns the coordinator enforces, each as written. It adds nothing else: session names stay null, the root stays ".", there is no process id, and a pattern the coordinator rejected shows only in its count. detail is matched ignoring case;
    • without the header the answer is 403, after the Host check (403) and the bearer check (401). The header keeps the view from being fetched and pasted by accident; it is not authentication, since anything that holds the bearer secret can send it;
    • every tier carries pre_edit_if_unheld: true at the top level, so a client can tell this coordinator, which refuses an opted-in pre-edit while another agent holds the file (see Added), from plugin 0.6.0, which takes the file from its holder;
    • a fresh pre-read answer for a tracked file carries version, the version of the record the read was checked against, including the answer that also delivers a queued notice, as the Python coordinator's answer does. Before, a client that read a file and then wrote it with compare-and-swap took version 0, so once the file had a committed version its write could not land. An untracked read is still answered {"status":"fresh"}.

    A CoherentVolume with managed globs, and the library's MCP server built on one, now attach by the glob check they apply to the Python coordinator, under either on_error and with no option to set, agent-coherence 0.15.0 included; a refuse-mode volume (on_held="refuse", in library releases after 0.15.0) attaches too. A volume needs this coordinator already running, with the volume's globs in .coherence/tracked.yaml and .coherence/strict_mode.yaml: a volume never starts it, and one built while no coordinator runs starts the Python coordinator instead, so start a Claude Code session in the workspace first. What differs from the Python coordinator:

    • there are no snapshot sessions or handoffs, so a multi-file atomic_publish and the handoff methods do not run;
    • gate() always holds, because the coordinator reports no ownership generation;
    • there are no caller principals, so a refuse-mode volume's opted-in writes go without one;
    • there is no sweep: an opted-in request reclaims a grant held 30 minutes or more;
    • Claude Code sessions never opt in, so their edits take a file a volume holds.

    Upgrade such a volume, and the MCP server, to the agent-coherence release that ships the matching change, a release after 0.15.0 (Cohexa-ai/agent-coherence#518). 0.15.0 keeps sending the workspace secret to a coordinator that has exited (Cohexa-ai/agent-coherence#503), and under on_error="degrade" its multi-file atomic_publish against this coordinator raises CommitUnconfirmed, saying the transport failed and to retry, on every attempt. README "Known limitations" lists what differs on this coordinator.

  • On the built-in Node coordinator, every spelling of a file reaches that one file (Cohexa-ai/agent-coherence#506). The coordinator identified a file by the exact path a client sent, but a macOS disk opens PLAN.MD and plan.md, or a composed and a decomposed é, as one file. One file could then get several records, each with its own write grant: an edit of DATA/X.TXT did not meet another agent's grant on data/x.txt, and a stale session's edit of PLAN.MD was admitted where a strict plan.md is denied. On every disk, ./data/x.txt, data//x.txt and data/./x.txt each got a record of their own, and .//data/x.txt slipped past strict mode. Now:

    • every spelling the workspace disk treats as one file, plus its ./ and // variants, reaches the same holder, the same refusal and the same strict-mode rule, and a tracked.yaml, ignored.yaml or strict_mode.yaml pattern matches all of them;
    • on a disk that folds nothing, names that differ only by case or accent form stay separate files, as before: only ./ segments and repeated / are tidied;
    • on a disk that folds names, a new record takes the disk's own spelling, of the file or, for one not created yet, of its existing directories, and every answer repeats the path exactly as the request sent it;
    • two spellings of one file in one Bash command count as one file.

    How the coordinator learns the disk:

    • once per start, under its single-writer lock and before it opens state.db, it creates and removes a few probe files inside .coherence, and nowhere else; no hook creates a file to find out;
    • /status shows the result in every tier: fold_profile is caseless (case and accent forms fold, as on the macOS default, case-insensitive APFS), nfd (accent forms only, as on case-sensitive APFS), none or cannot_tell, and fold_table_unicode is the Unicode version of the fold table, 17.0.0;
    • a disk it cannot classify (cannot_tell: HFS+, exFAT, FAT, a .coherence on another device than the workspace, a probe that fails) folds nothing, and coordinator.log says why, once;
    • a coordinator that runs without its single-writer lock folds nothing and merges nothing.

    Records an older build split for one file:

    • at the first start they are merged into one record when their names still reach the same file on disk, ./ and // splits included;
    • at most one write grant survives: the single write holder of the record whose content matches the file on disk keeps it, and when no single holder fits, nobody does;
    • every other agent on the file stays on it as stale: a holder that lost its write grant gets a notice, and its next commit is refused (commit_not_allowed) until it reads the file again;
    • records whose file is missing at start are not merged but act as one file, and coordinator.log names each merge.

    Names that are not files: a request that sends "name_kind": "key" names an object or row key, which is kept and matched exactly, never tidied, folded or merged. A value other than "file" (the default) or "key" is refused with HTTP 400, as an invalid path is. The plugin's hooks never send the field.

    Links and the workspace root, in the plugin's Node hook client, which the hooks run on either backend wherever it is installed and node is on PATH, so a workspace the Python coordinator serves sees these changes too:

    • it follows links, as the Python hook client does: a Read, Edit or Write through a link reaches the coordinator under the path of the file the link names, so a file reached through a linked directory matches patterns written against its target's path, not the link's. When it loads or reloads the policy, the coordinator logs each tracked or strict pattern whose directories pass through a link inside the workspace, or that names a link to a file, and says when the link's target is outside the workspace, where a Read, Edit or Write through it is not coordinated and no pattern can cover it;
    • a Read, Edit or Write through a link inside the workspace that points outside it, or through a link that does not resolve, is no longer coordinated: the hook stays out of it, as for any path outside the workspace. A Bash command's file arguments are still matched as typed, a link among them included;
    • a tool path that spells the workspace root differently from the disk (another case, or /var for /private/var on macOS) now reaches the coordinator, where the hook skipped it before; one that spells the root as the disk does keeps the case it was typed in, as the Python hook client and a Bash command's arguments do.

    Also:

    • the Node coordinator refuses a path over 1024 characters (counted as Unicode code points) with HTTP 400, as the Python coordinator does; a Bash argument still that long once its ./ and // are tidied is matched as typed;
    • on a disk that folds names, a Grep's search directory reaches the tracked files under every spelling the disk treats as that directory, and no other; on other disks it matches as before, ignoring ASCII case;
    • upgrade the agent-coherence library's CoherentVolume and MCP server together with this coordinator, to the library release that ships the same change (a release after 0.15.0): older releases compare paths exactly as they spelled them, so they can miss a file this coordinator records under the disk's spelling. The Python coordinator does the same in agent-coherence releases after 0.15.0.

    README "Known limitations" lists what this does not cover.

  • On the built-in Node coordinator, a CoherentVolume attempt that the volume reports ended leaves the coordinator's records and /status (Cohexa-ai/agent-coherence#525). A program that uses the agent-coherence library's CoherentVolume starts new attempts over time, each its own agent identity, and every attempt kept its rows in .coherence/state.db and its row in /status after it was over. A session-stop can now carry "ended": true with the attempt's agent_id. The Node coordinator then releases the attempt's write grants as before and deletes its records: its state on each file, its heartbeat and its queued notices, so /status stops listing it. While the attempt still holds a write grant, for example after a failed release, it deletes nothing and keeps every row. A file state that records a reclaim also stays, as INVALID, so the attempt no longer counts as a reader of that file. An ended that is not a boolean, or is true without an agent_id, answers HTTP 400; a stop without ended, or with false, answers as before. Claude Code sessions and subagents are unchanged: the plugin's hooks never send ended, so a stopped session or subagent keeps its rows. The library's volume sends the flag in agent-coherence releases after 0.15.0, where the Python coordinator does the same.

  • On the built-in Node coordinator, a session keeps a read of each file it releases, so it can read and edit a file it edited in an earlier turn (Cohexa-ai/agent-coherence#513). The Stop hook releases every EXCLUSIVE or MODIFIED grant a session holds at the end of its turn, SubagentStop does the same for a stopped subagent, and a failed Edit or Write releases the grant its pre-edit took. Each release left the session's own copy INVALID, as if another agent had taken the file. In strict mode, the session's next Read and Edit of a file it had edited and committed were then denied with Stale read denied: your grant on <path> was revoked and no new version was committed, and every retried Read was denied again; in warn mode, its next Read carried a warning that its grant had been revoked. Now a release leaves the session a reader (SHARED) at the version it last saw. While nothing has changed the file since, its next Read is fresh and its next Edit is admitted; /agent-coherence:status lists the session as SHARED on the file, and re-grounding after compaction lists the file as a held grant (At compaction you held SHARED on spec.md (v1) — re-acquire before writing.) where it said spec.md is at v1.. A release changes nothing for a session that holds no write grant on the file: a reader stays a reader, and a copy that another agent's edit or commit made stale stays stale and is still denied. One exception in warn mode: a session can still edit a file another session changed since its last read, and that edit takes the session's write grant. If the edit fails or the turn ends, the session keeps a read of the file's current version although it never read that version, so its next Read is fresh and no stale warning is shown, where before it was warned. Strict mode denies that edit, so there the copy stays stale. A file changed after its edit was committed, for example by a formatter hook that runs after every edit, still reads as changed outside the coordinator on the next turn. Hook answer shapes and deny texts are unchanged. One reason text changes: a commit refused after the session's own release, such as a successful Edit reported after the same session's failed Edit of the file, gets a commit_not_allowed reason that names the session's state as SHARED, where it said INVALID. A session already denied its own file this way stays denied after the upgrade, because the store does not record who made its copy stale: clear it as README "Strict mode" describes, with a Bash command that reads the file, or start a new session. The Python coordinator does the same in agent-coherence releases after 0.15.0.

  • On the built-in Node coordinator, a policy pattern without ** now matches the files it matches on the Python coordinator (#209). The Python coordinator matches a tracked.yaml, ignored.yaml or strict_mode.yaml pattern without ** as fnmatch does: * and ? also match /, and [...] is a character class. The Node coordinator read every pattern as it reads one with **, where * and ? stay within a directory and [ is an ordinary character, so the same policy selected different files on the two backends: a strict data/[0-9].json enforced data/5.json on Python and only a file literally named data/[0-9].json on Node, and a strict src/*.py reached src/x/y.py on Python only. Now, on a workspace the Node coordinator serves:

    • a pattern without ** reaches nested files (docs/*.md matches docs/a/b.md), ? matches /, and data/[ab].json matches data/a.json and data/b.json and no longer the file literally named data/[ab].json;
    • an ignored.yaml entry without ** untracks every path it now reaches, nested ones included;
    • /agent-coherence:untrack decides whether an entry covers a strict pattern by these rules (see the strict-path entry under Fixed): *.json and data?a.json are refused against a strict data/*.json, and data/?ab?.json is not refused against a strict data/[ab].json, which names data/a.json and data/b.json. On a disk that folds nothing it decides each entry as the Python coordinator does from agent-coherence 0.15.0, under the same search budgets.

    A pattern containing ** matches as before. Check .coherence/tracked.yaml, ignored.yaml and strict_mode.yaml for entries without **: they may now reach more files than intended. A tracked *.md, for example, now tracks every .md file in the workspace, not only those at its root.

  • On the built-in Node coordinator, a file changed outside the coordinator is now named as such (#205). When a session holding a grant reads a tracked file whose bytes are not the recorded content, at the version it already holds, no session committed the change: a script, an editor or a shell write the hooks never saw made it. In strict mode the read is denied with its own reason, which names no writer and tells the agent not to restore or overwrite the file and to tell its user; before, the deny named the last committer or agent <unknown>. In warn mode the read, which said nothing, now carries hash_differs and a notice saying the same, as context only. The read check now applies to any session holding a grant, not only one holding a read (SHARED), so in strict mode a session that holds the file for writing is now denied too when its bytes changed this way. The Python coordinator already checks any holder's read in agent-coherence 0.15.0, where the deny names the last committer and warn mode sets only hash_differs. Its deny reason, notice and pre-edit check match this entry in agent-coherence releases after 0.15.0. Before an Edit or Write the coordinator now hashes the file on disk itself, and when it no longer holds the recorded content the edit is admitted with disk_differs and the notice; it never denies. The read stays denied until the change is committed through the coordinator; an Edit or Write of the file is still admitted. While another session holds an uncommitted write claim on the file, the pre-edit check is skipped, because that session's write may still be landing.

  • A session start that refuses a workspace for its .coherence now tells the model that it started no coordinator, not only you (#251). A coordinator that would not start was reported only on the session-start hook's stderr, which Claude Code shows to you and not to the model, so the model went on as if its edits were coordinated. A session start that refuses a workspace (see Fixed) now exits 0 and prints one SessionStart JSON object. Its systemMessage reads agent-coherence started no coordinator for this session: <why>. <fix>, where <why> names the entry and says it is a symlink, is not a directory, or is a FIFO, socket or device (.coherence/hook.secret is a symlink), and <fix> says what to do: for a link at .coherence itself, to replace it with a real directory, and for a link at state.db or one of its sidecars, to move state.db together with its -wal and -shm, and otherwise to replace the link with a copy of the file it names or mount a directory at .coherence, to move a non-directory aside, or to remove a FIFO, socket or device. Its additionalContext tells the model that this session start did not start a coordinator and why, that hooks may still answer from a coordinator already running for the workspace, so it should treat any warning or deny they give as real and not assume its edits are coordinated otherwise, and to tell you. The stderr line agent-coherence: not starting the coordinator: <why>. <fix> says the same. Any other failure to start a coordinator is reported on stderr only, as before.

  • On the built-in Node coordinator, .coherence/server.port is no longer written. The coordinator wrote its port there as well as into server.pid, and the write followed a link, so a repository that committed server.port as a link had the file it names overwritten at every coordinator start. Nothing in the plugin read the file: the hook client, the CLIs and the session start take the port from the second line of server.pid, and the Python coordinator writes no server.port. One that an earlier release wrote stays as it is; nothing reads it, so you can delete it. A script that read the port from it should read the second line of server.pid instead.

  • The Node coordinator's uuid dependency is updated from 14.0.2 to 14.0.3 (#196). The first Node-backend session after the upgrade installs it, as it reinstalls the Node backend's dependencies after every plugin upgrade.

Fixed

  • Claude Code no longer prints an unknown-keys notice for the plugin's hooks.json at every session start (#259). Claude Code 2.1.319 names every key it does not recognise at the top level or in a matcher group of hooks/hooks.json, and the file carried five _comment keys, so every session start printed agent-coherence: hooks.json: unknown keys "_comment", … ignored. The hooks ran as before. The comments now live in the hook client's source, and a test keeps hooks.json to the keys Claude Code accepts.

  • The session start now starts the coordinator when the plugin is installed under a path that contains a space (#220). The SessionStart hook ran bin/ensure-coordinator-dispatch through an unquoted ${CLAUDE_PLUGIN_ROOT}, the only hook command in hooks/hooks.json left unquoted, so the shell split the path at the space and ran a command that does not exist. No coordinator started, on either backend, and unless one was already running for the workspace every hook answered as with no coordinator: no stale-read warnings and no strict-mode denies. The path is now quoted like the other hook commands, and a test checks that every ${CLAUDE_PLUGIN_ROOT} path in hooks.json is quoted.

  • On the built-in Node coordinator, a session started in a subdirectory or a linked worktree of a repository now starts its coordinator at the repository root, where the hooks look for it (#254). The session start ran the Node coordinator in the directory the session started in, while every hook and /agent-coherence:* command looks for it at the root of the repository, the main one for a linked worktree. Such a session's hooks reached only a coordinator another session had started at the root, or none, and the one its own start ran served no one and never stopped. Outside a git repository, where the hooks and commands use no coordinator, the session start now starts none, as the Python backend's session start already did not. A .coherence directory an earlier session created in a subdirectory or a linked worktree is no longer used and can be deleted. Stop the coordinator it names first: check that ps -p "$(head -n 1 <dir>/.coherence/server.pid)" -o command= names dist/coordinator.js, then kill that pid. One an earlier release started keeps running when its directory goes.

  • The built-in Node coordinator now stops by itself once no client can reach it (#234). Clients find a coordinator only through .coherence/server.pid, and the coordinator stopped only on SIGINT or SIGTERM. One whose workspace was removed, for example with a git worktree, or whose server.pid was deleted or replaced, ran on for days with nothing able to reach it. It now checks server.pid every 5 seconds and stops, as on SIGTERM, once the file is gone, is another file, or no longer holds exactly what this coordinator wrote, as when another coordinator rewrites it. Deleting the .coherence directory of a workspace it serves therefore stops it within a few seconds. Nothing starts another before the next session start, resume, /clear or compaction, so until then the hooks answer as with no coordinator (#265). It still does not stop when idle; the Python coordinator stops after 15 idle minutes.

  • The hook client and the /agent-coherence:status, /agent-coherence:track and /agent-coherence:untrack commands now send nothing to a coordinator that has exited (Cohexa-ai/agent-coherence#503). They find the coordinator through the port in .coherence/server.pid and send the workspace's bearer secret with every request. A coordinator that exited without a stop, for example one that was killed, left its port in that file. Once the port was free, any local process could bind it, receive the secret with the next hook or command, and have its answers believed. Now:

    • Before they send anything, they read server.pid and probe the workspace lock, the flock a running coordinator holds on that file, with a shared lock they drop at once, so a probe never reads as a coordinator to another client or to a session start. A free lock means the coordinator is gone: a hook answers {}, as with no coordinator, and a command exits 2 with no coordinator running for this workspace (<workspace>/.coherence/server.pid names pid <pid>, which no longer holds the workspace lock); start one.
    • Before every later request they read server.pid again, and send nothing, without opening a connection, when it names another pid or port than the one they found, has lost its port line to a stop, names a coordinator whose lock is now free, has become a link, is not a regular file or is over 4096 bytes, or when .coherence has become a link. A command then prints the reason, ending ; nothing was sent, and exits 2; /agent-coherence:track and /agent-coherence:untrack then print none of the paths they rejected themselves, as when they find no coordinator.
    • A Node coordinator writes backend=node into server.pid, and runs without the lock where it cannot take one: on Linux with neither perl nor flock(1), or on a file system that refuses it. It is judged by its pid unless the lock is seen held, also where no lock tool can probe: a pid that no longer runs means it exited. It removes server.pid when it stops unlocked, so a hook attached to it keeps working while its pid runs, and sends nothing once the pid is gone.
    • What still sends: a coordinator that holds the lock; for a server.pid without backend=node, a lock this host cannot probe, because neither perl nor flock(1) is installed on Linux or the file system cannot lock; a server.pid that is gone or cannot be read at a later request, unless it named a Node coordinator whose pid no longer runs; and a Node pid this process may not signal (EPERM), which a sandbox that denies signals also answers for this user's own running process.
    • The hook client and the CLIs read server.pid as a regular file only, never through a link, including where the hook client reads its backend= line before a caller-principal claim. A linked server.pid is refused with the same message as a link elsewhere in .coherence, and one that is not a regular file with <workspace>/.coherence/server.pid is not a regular file; restart the coordinator.

    A server.pid written by hand for a process that does not hold the lock and has no backend=node line no longer counts as a running coordinator. Where the plugin's Node client is not installed (no node on PATH, or no Node-backend session has built it on this machine yet), the hooks and commands run the agent-coherence library's clients instead, which make the same check in agent-coherence releases after 0.15.0. SECURITY.md says what the check cannot see.

  • A session start and the built-in Node coordinator now refuse a workspace whose .coherence is a symlink or holds one, and a policy file linked to a FIFO no longer hangs the Node coordinator (#251, #248). A repository can commit .coherence, or any file in it, as a symbolic link, and an archive can unpack one. The session start and the Node coordinator then read and wrote through it: the coordinator kept its state in whatever directory a linked .coherence named, opened state.db where a link pointed, took the bytes of the file a linked hook.secret named as its bearer secret, and overwrote whatever a linked server.port named; the hook client sent that file as its bearer; and a link to a FIFO held the session start, or a hook or CLI, until it timed out. A tracked.yaml or ignored.yaml linked to a FIFO blocked the coordinator's only thread at the next /agent-coherence:track or /agent-coherence:untrack: it answered nothing, not even /health, and SIGTERM did not stop it. Now:

    • .coherence must be absent or a real directory, and nothing directly inside it may be a symlink, a FIFO, a socket or a device. A directory mounted at .coherence is a real directory and passes. The session start checks this before it reads or writes anything under .coherence, on either backend, whether or not COHERENCE_COORDINATOR_BACKEND is set. The check only tests file types and lists the directory, so nothing it finds can hold it, and a .coherence it cannot list passes, for the coordinator to decide. A refused session start prints agent-coherence: not starting the coordinator: .coherence/<name> is a symlink. and what to do, starts no coordinator, and tells the model (see Changed).
    • The Node coordinator makes the same check at start, before it creates, locks or writes anything, so a coordinator started some other way refuses too. It prints one line naming the entry and the way out, and exits 2. For a linked hook.secret it says refusing <workspace>/.coherence/hook.secret: it is a symlink, and .coherence must be a real directory with no link directly inside it. Replace the link with a copy of the file it names, or mount a directory at <workspace>/.coherence.
    • The coordinator, the hook client and the CLIs read hook.secret without following a link, without blocking and from a regular file only, and the hook client refuses a .coherence that is a link before it reads anything inside it. A linked hook.secret is never sent as the bearer: a hook answers {}, as with no coordinator, and the coordinator does not start. A hook.secret over 4096 bytes is no longer read whole: the hook client reads it as missing, and the coordinator as malformed.
    • The coordinator reads the policy files the same way. /agent-coherence:track and /agent-coherence:untrack over a tracked.yaml or ignored.yaml that is a link answer HTTP 400 at once, with .coherence/tracked.yaml is a symlink; nothing was written. Replace it with a copy of the file it names, or mount a directory at .coherence. (or the same for ignored.yaml), and leave the link and the file it names as they are; before, a link to a regular file was read, then replaced with a regular file. For a FIFO or a device at that name they answer HTTP 400 with .coherence/tracked.yaml could not be read (not a regular file); nothing was written. The coordinator never waits on either, so /health and SIGTERM keep working. A policy file that is a link when the coordinator loads it, for example one made after the start and loaded after a track or untrack, loads as no entries, logs agent-coherence: WARNING — <path> is a symlink; it loads as no entries, and counts as one rejected entry on /status, with the reason a symlink, so the file loads as no entries.
    • The coordinator creates .coherence/.gitignore, and the first Node-backend session on a fresh workspace writes .coherence/coordinator_backend, only where nothing is at that name, so neither follows a link made after the check, nor waits on a FIFO already there when it writes. An operator's .gitignore or coordinator_backend is still never overwritten.

    Not covered: committed regular files under .coherence, which are out of scope here, and a link above .coherence. SECURITY.md describes the threat. The hook client and the CLIs also read .coherence/server.pid without following a link (see the entry on a coordinator that has exited).

  • On the built-in Node coordinator, a workspace now has one coordinator, and a coordinator that stops no longer leaves another one unreachable (#217). Nothing stopped a second Node coordinator starting for a workspace: two sessions starting at once each started one. A session whose check took an unrelated process, reusing a dead coordinator's pid, for the coordinator started none, so the workspace had no coordinator at all. Two coordinators both served, each writing its own port into .coherence/server.pid, so hooks reached whichever wrote last, and a path tracked or untracked through one stayed as it was on the other until it restarted. On a fresh workspace one of the two could instead fail start-up with table artifacts already exists. The first to stop deleted server.pid, leaving the other running where no hook could find it. The Python coordinator could not see a running Node coordinator either: a Python start found the lock free, took it, and refused the Node store. Now:

    • The coordinator locks server.pid for as long as it runs, with the flock the Python coordinator takes on the same file, before it opens state.db. A second Node coordinator finds the lock held, whichever backend holds it, logs another coordinator holds …; exiting to coordinator.log and exits without touching the store. The session that started it is told another coordinator already serves the workspace and is not reported as failed.
    • A coordinator that stops removes the port line from server.pid instead of deleting the file, as the Python coordinator does. The lock is on that file, so the next coordinator must lock the same one. Do not delete server.pid yourself: a Python coordinator, or a Node coordinator an earlier plugin release started, keeps running where no later coordinator can see it, so a second one starts beside it. A Node coordinator from this release stops within 5 seconds instead (see the entry on a coordinator no client can reach). The README's troubleshooting row that said to remove it now says not to.
    • The session-start check asks whether the lock is held and a port published instead of whether the pid in server.pid is alive, so a pid now used by another process no longer passes for a coordinator. A coordinator that holds the lock without a port, because it is starting or stopping, no longer counts as running either: the session starts one that waits for the lock, so it joins that coordinator once it serves or takes over once it stops. A coordinator that a plugin version before this one started holds no lock; while it runs, it still counts as running.
    • A Python start now finds the lock held and joins a running Node coordinator instead of refusing its store, agent-coherence 0.15.0 included, and the store check that agent-coherence releases after 0.15.0 add (agent-coherence-coordinator --check-store) reports it as live.
    • A coordinator no longer writes through a server.pid that is a symlink, which a repository could commit so that every coordinator start overwrote the file it points at. It refuses to start instead, as for any link in .coherence, and the session start refuses such a workspace before it starts one (see the .coherence entry above).
    • The coordinator runs in a session of its own, so a signal to the session-start hook's process group, as on a hook timeout, no longer reaches it.

    On macOS the lock is taken as the file is opened. On Linux it takes perl or flock(1) (util-linux or BusyBox); a host with neither runs unlocked, as before, and the coordinator says so in coordinator.log.

  • The README now says which backend tracks DECISIONS.md by default, and no longer promises a strict-mode warning nothing emits (#228, #226). DECISIONS.md is a default tracked file on the Node coordinator only; the Python coordinator's defaults have never included it. The README listed it among the watched files for both backends. It now says Node only, and Known limitations explains what changes on a Python-backend workspace and how to track the file there. The README also said a ** in strict_mode.yaml triggered a startup warning past 50 tracked artifacts, so the plugin would never silently lock down a workspace. Neither coordinator emits that warning. It now says strict mode applies only to tracked paths, that a strict **, or a strict * (which, in a pattern without **, matches across /), puts every tracked artifact in strict mode, and that nothing warns about it. Behavior is unchanged.

  • On the built-in Node coordinator, a session start no longer reports a coordinator that dies during start-up as running. After starting the coordinator, the bootstrap waited a fixed half second and called it spawned if the process was still alive. A coordinator fails start-up only after loading its native module and opening .coherence/state.db, which took 1.3 to 1.7 s on a heavily loaded machine, for example with many sessions starting at once. So a coordinator that died then was reported as spawned, and the session's hooks found no coordinator and silently did nothing. On a fresh workspace, .coherence/coordinator_backend was also set to node although Node never started, which turned off the fallback to the Python backend for every later session. And a crash from a native module built for another Node version skipped the self-heal that reinstalls it, so the next session crashed the same way. The bootstrap now waits until a coordinator serves the workspace or the one it started exits; a coordinator writes .coherence/server.pid naming itself once its port is bound, which takes about 0.2 s on an idle machine. The wait ends as well when another session's coordinator starts serving first. A coordinator that exits first is reported as failed, with the end of its log. One still alive but not serving after 10 s gets a warning and is let through as before, since it may only be slow.

  • agent-coherence-untrack and agent-coherence-track no longer drop rejected paths when the request fails or is refused (#212). When /agent-coherence:untrack was refused because a path is enforced in strict mode (exit 3), the bundled CLI printed only the refused paths, and dropped both the paths the coordinator rejected in the same answer and the paths the CLI rejected itself, such as ../outside. An operator learned about them only after fixing the strict entry and running the command again. Both lists are now printed before the closing line. Every exit 2 after the request was sent (an HTTP error, a non-JSON or malformed answer, a timeout, or a connection closed before the answer was complete) now also prints the CLI's own rejections, for track as for untrack; with no coordinator found, nothing is sent and they stay unprinted. Exit codes are unchanged.

  • On the built-in Node coordinator, a hook whose store work fails now answers the Python coordinator's failure envelope (#214). When a registry call raised, for example with database is locked while another process held .coherence/state.db's write lock, pre-read, pre-bash and pre-grep answered HTTP 500, and pre-edit, post-edit and post-edit-cas answered {ok: false, reason: "database is locked"}, the same shape as a lost grant. Every hook route now answers HTTP 200 {ok: false, reason: "internal: <ErrorType>"}, the Python coordinator's failure envelope. agent-coherence releases after 0.15.0 type it by its internal: prefix: a strict read raises CoordinatorFailed, and a commit that hit a busy store raises CommitUnconfirmed and releases the writer's grant. With agent-coherence 0.15.0 a CoherentVolume still reads that commit answer as CommitPreempted and keeps the grant. A refusal such as commit_not_allowed keeps its own reason. Session-stop no longer answers a clean release while a store fault left the grant held, and a session-start whose context fails to build answers the envelope instead of {}. /policy/track, /policy/untrack and /status keep answering HTTP 500, as on the Python coordinator.

  • On the built-in Node coordinator, a policy file that loads as no entries now counts as rejected on /status (#192). A .coherence/tracked.yaml, ignored.yaml or strict_mode.yaml that is not valid YAML, whose top level is not a list, or that cannot be read loaded as no entries with only a warning in coordinator.log, which nothing on /status reflected, so policy_summary.rejected_pattern_count stayed 0 and a workspace whose tracked.yaml no longer loads looked exactly like one with no user patterns. Such files exist: plugin v0.3.0 to v0.5.0 wrote entries such as - *.md unquoted (#178), and when the lost entry is the tracked glob a strict path depends on, that path leaves strict mode at the next coordinator start. Each such file is now recorded as one rejected entry named .coherence/<file>, with the reason the Python coordinator gives from agent-coherence 0.15.0 ("not valid YAML", "top level is , not a list", "could not be read", each "so the file loads as no entries"), so both backends report the same count for a file both YAML loaders read the same way. A missing, empty or null file still records nothing. policy_summary also gains strict_mode_pattern_count, which the Python coordinator already reports, between ignored_pattern_count and rejected_pattern_count; a client that reads it from /status, such as CoherentVolume.strict_mode_active() on a volume attached without managed globs, now gets the count instead of a missing key, which it read as strict mode off. An unreadable file is no longer logged as "malformed YAML".

  • On the built-in Node coordinator, a policy file entry that is not a string can no longer stop the coordinator starting or stall it. Since v0.1.1 the coordinator recorded such an entry as rejected by converting it to text with the entry's own conversion, which a committed .coherence/tracked.yaml, ignored.yaml or strict_mode.yaml controls. An entry of - {toString: 1} made that conversion throw: present at start-up, it stopped the coordinator starting; added while it ran, it made every later /agent-coherence:track and /agent-coherence:untrack write its entry and then answer HTTP 500. An entry of nested YAML aliases, under 300 bytes, built a string of about 194 million characters on every load and reload, holding the coordinator's one thread for over 5 seconds each time; one level deeper exceeded the string length limit and threw. A non-string entry is now recorded without converting it: a list as <list>, a mapping as <dict>, a date as <date> or <datetime> and binary data as <bytes>, while a number, boolean or null keeps its plain text. It still counts as one rejected entry with the same reason, so policy_summary.rejected_pattern_count on /status is unchanged.

  • On the built-in Node coordinator, a strict path now stays enforced while the coordinator runs (#177, Cohexa-ai/agent-coherence#261). Untracking a path that .coherence/strict_mode.yaml enforces, or listing it in ignored.yaml, took it out of strict mode and onto the untracked path, where a read reports version 0 and a CAS commit is accepted at any expected version, so a stale write could overwrite a newer one with nothing raised. Now:

    • /agent-coherence:untrack refuses an entry, a path or a glob, that covers a strict path, writes nothing for the whole request, and agent-coherence-untrack names the strict pattern and exits 3. The coordinator answers HTTP 409 with reason: "untrack_strict_path", as the Python coordinator does from agent-coherence 0.15.0. Whether an entry covers a strict path is decided on the patterns themselves, so data/**, ** and ./data/a.json are all refused for a strict data/*.json; a decision too costly to finish counts as covering, so the answer errs toward refusing.
    • An ignored.yaml entry never takes a strict path out of strict mode, however broad. It still untracks every path no strict pattern matches. At start-up the coordinator names any ignored entry that strict overrides, in its log (coordinator.log in the plugin's data directory).
    • While strict patterns are live, a track or untrack no longer drops a strict or tracked pattern the running coordinator holds, even if its file was edited by hand in the meantime.

    To stop enforcing a strict path, remove its entry from .coherence/strict_mode.yaml and restart the coordinator: from the workspace root, check that ps -p "$(head -n 1 .coherence/server.pid)" -o command= names dist/coordinator.js, stop it with kill "$(head -n 1 .coherence/server.pid)", then start or resume a session, which starts a new one. A workspace that relied on an ignored.yaml entry to switch strict mode off for a path finds that path enforced again after upgrading.

  • On the built-in Node coordinator, a pattern with many * or ** runs no longer stalls every hook. The coordinator matched each pattern with a regular expression that backtracks into every run: an entry such as "**".repeat(12) + "Z", which any track or untrack could add, took 5.9 seconds on a 21-character path and longer on longer ones, and every hook matches every path against every pattern on the coordinator's one thread. Two runs were enough on a long path: **a**Z took about 2 seconds on a 50,000-character one, and a Bash command's file arguments have no length limit below the request cap. A pattern with ** and more than one run is now matched in time linear in the path, with the same results. A pattern without ** is matched as fnmatch does (see above), also without backtracking. The untrack check described above is bounded the same way: each step of its search costs about the work it is charged for, so a request that spends its whole budget still answers in well under a second.

  • The [0.6.0] entries in this changelog now say which backend each change covers, and correct several details. Most coordinator changes in 0.6.0 are in the plugin's built-in Node coordinator; a workspace served by the Python coordinator gets the matching behavior only from agent-coherence releases after 0.14.1. The corrected section also fixes the field names in the CLI shape-check entry (added and removed), what the CLIs printed before 0.6.0, and the preemption-notice size figures, and adds entries for changes it had left out: hook texts now say agent where they said session, the version a stale warning reports, the uuid runtime dependency bump and the non-2xx output of track and untrack. The GitHub Release notes for v0.6.0 carry the same text.

  • PRIVACY.md and SECURITY.md list every case in which provisioning reinstalls the Node backend's dependencies, not only the first session and an upgrade: also after a switch to a different Node major version, and whenever the installed native module fails to load, such as on the session after an interrupted install.

  • /agent-coherence:track and /agent-coherence:untrack say what happens when the CLI gets no paths. They said argparse would error, which is true only of the Python console script (exit 2 with a usage message); the bundled Node CLI exits 1 with no output.

Internal

  • Tests that stand for a Stop or a failed edit now go through the release those hooks make. Several registry and hook tests called the registry's invalidate to put a session where a Stop or a failed Edit leaves it, and two failure-envelope tests made invalidate throw to fake a busy store during those hooks. They now call releaseToReader, or make it throw, since the hooks no longer call invalidate, so no test models a release the hooks do not make. Tests that need an INVALID row, such as the /status check that leaves INVALID rows out, still call invalidate.

  • The dispatcher and bin-shim tests no longer fail when the whole suite runs on a busy Mac (#219). Each test wrote stub executables (bootstraps, a fake node, a fake console script) and ran them for the first time inside a 10 s or 5 s spawn timeout. macOS checks an executable the first time it runs, and while the suite runs in parallel those checks queue, so a first run took over 3 s and a test failed at its timeout; Linux, and so CI, does no such check. Every test that writes an executable and runs it directly now writes it through one helper that runs it once, untimed, as it is written; the dispatcher tests write their stubs once per file; and the bin-shim tests run each of this repo's shims once before timing it, since a fresh checkout or worktree writes those files anew too. Under the same load each dispatcher test takes about 0.2 s instead of 3 to 8 s. The spawn timeouts are unchanged.

  • The Node coordinator parses a policy glob in one place (#213). The regex a pattern with ** and at most one * or ** run is matched by is now built from the same tokens the linear matcher and the strict-coverage search read, as the Python coordinator builds its ** regex, so a change to the glob syntax is made once. The refactor changes no match: over 1.7 million patterns, the new regex is byte-identical to the old one.

  • A test pins how the hook client's transport rejects a request the coordinator never answers.