@ssheleg/agent-sync 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,3 +1,94 @@
+## v1.18.0 — a third backend, and two people who can finally see each other
+
+`fs` keeps the record on one machine and `outline` costs $10 a month for a team; between
+them sat the case this release is for — **two people, two machines, one plane, nothing to
+pay**. `notion` is that plane. The container is a page, every log is a child page of it,
+and every line is one paragraph block appended by `PATCH /v1/blocks/{id}/children`, which
+is a server-side append with no read-modify-write anywhere in the class.
+
+**The capability flags are earned, and the earning found two defects.**
+`test/notion_live_test.py` ran against a live workspace on 2026-08-25 and passed on the
+fourth attempt: `200 appends from two processes, 200 lines on one page`, `two reads return
+one order`, `tree.ensure is idempotent`, `both fresh shards enumerated, 200 lines across
+them`, and the forced degradation. The three runs before it are the reason to trust the
+fourth. Run two went red at 171 lines with a dead writer: the retry path had never executed
+in run one, and it turned out `TimeoutError` is an `OSError` rather than a `URLError`, so a
+read that timed out **after** the connection was established fell past both retry branches
+into the catch-all and failed permanently. Run three went red differently — 100 lines, all
+from one writer, both exiting 0 — because the two writers each called `tree.ensure` on a
+shared title and the check-then-create raced into two pages of that name. That one is a
+finding about the measurement: `Sync.log_id()` says *this run's OWN shard, one writer per
+document, always*, so the protocol never creates it. The contention case is now handed the
+page id, and the case the sharded design actually depends on took its place — two fresh
+shards, both enumerated, which is precisely what Outline's search index could not do.
+
+The suite covers both halves of the retry loop now. The success half had never existed:
+every assertion drove a transport that always failed, so nothing measured whether a retry
+can succeed — a loop that cannot is a loop that only fails more slowly.
+
+It needs credentials and a network, so it stays outside `npm test` and **says SKIP loudly**
+rather than passing quietly where it cannot run. `exclusiveLease` stays false and no
+measurement can move it: Notion has no compare-and-swap, and the endpoint's own
+`conflict_error` is a retry hint rather than an arbiter.
+
+**One registry of backends, because three copies of a two-item list is how a backend comes
+to half-exist.** `CLOUD_ADAPTERS` is the single home; `init`'s argument parser, `check`'s
+known-adapter test and `bootstrap`'s dispatch all read it. `bootstrap` used to build an
+Outline collection whatever the project was configured for — on an `fs` project it demanded
+Outline credentials for a backend that has no container at all. `check`'s credential test
+now asks the adapter (`REQUIRED_ENV`, `preflight()`) instead of naming Outline's variables
+in an `if`, and the Notion preflight is a real call — `GET /v1/users/me` — because "knowledge
+base reachable" printed after a function that only parsed a string is the defect class this
+suite exists to refuse.
+
+**B-34's other half.** `_allocated_ids` still read `nextFreeIdPattern` directly while
+`id_pattern()` beside it accepted both keys, so a config written with the modern `pattern`
+key never discarded its own *Next free ID* line: `--set-baseline` stamped one above reality,
+and every id at the true top read as pre-baseline and was never asked for an as-built
+record. Reproduced in `fabric` on 2026-08-25, fixed here, fixture plants it back.
+
+**`FsAdapter`'s docstring said its files are "committed and pushed"** while `check` reports a
+tracked `.agent-sync/` as a problem — a committed run id hands one checkout's identity to
+every clone. The check was right; the line now says so.
+
+**And a defect in the suite itself.** `Sync()` calls `load_env_file`, which writes the
+project's variables into `os.environ` — correct for the CLI, a leak in-process. Two checks
+built temporary `fs` projects and left `AGENT_SYNC_BACKEND=fs` behind, and that variable
+OVERRIDES the configured backend, so the next check to depend on it silently read the
+previous check's project. The new dispatch check passed alone and failed in the suite, which
+is the signature of this class rather than of the code under test. Every check now runs
+through `_guarded`, which restores the environment and the working directory after it.
+
+Five checks, five planted defects: 51 → 56 fixtures.
+
+## v1.17.0 — the identity that had never once been established
+
+`_session_key()` falls back to one `shared` entry per checkout when it cannot tell which
+session is asking, and everything downstream hedges about it: `classify_lock` answers
+`ambiguous` rather than `reapable`, so an expired lease can never be cleared by the run that
+took it. The fallback was documented as the rare case.
+
+It was the only case. Measured 2026-08-25 in a checkout that had been running the tool all
+day: `.agent-sync/sessions` did not exist, and `.agent-sync/run-id` held exactly one key —
+`shared`. The stamping block in `session-start.sh` required `CLAUDE_SESSION_ID` in the hook's
+**environment**, and Claude Code delivers the id to a hook on **stdin as JSON**, which is how
+`guard.sh` next to it has always read its own payload. So the block had never run, in any
+session, since it was written. A fallback that is always taken is not a fallback.
+
+The hook reads its payload now, with the environment variable still winning where it exists.
+`test/hooks_session_test.py` runs the real hook as a process — the only way this was ever
+going to be caught, because every unit around it was correct — and covers the four ways it
+must behave: an id from stdin is stamped, an id from the environment still wins, a payload
+carrying no id stamps nothing rather than keying every session alike, and a payload that is
+not JSON leaves the hook exit 0, because a SessionStart hook that throws takes the session
+with it. A fifth case walks the whole chain: stamp, then the descendant's key, then the
+run-id map, then `classify_lock` returning `reapable` where it used to return `ambiguous`.
+
+Watched failing against the previous hook: 2 of the 5 cases red, and green after.
+
+Also: the README no longer tells a reader to run `python3 test/validate.py` and `npm test`
+from a package that ships no `test/` directory. It names where they run.
+
 ## Unreleased — both `AS-01` halves exercised outside their fixtures
 
 The two rows sat at priority `unverified`: shipped, and confirmed by nothing but their own

package/README.md

@@ -3,6 +3,13 @@
 [![CI](https://github.com/ssheleg/agent-sync/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/agent-sync/actions/workflows/validate.yml)
 [![npm](https://img.shields.io/npm/v/%40ssheleg%2Fagent-sync)](https://www.npmjs.com/package/@ssheleg/agent-sync)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![site](https://img.shields.io/badge/docs-skills.sshlg.me-8ab0ff)](https://skills.sshlg.me/skills/agent-sync/)
+
+**[Docs, and every skill →](https://skills.sshlg.me/)** · [this skill's page](https://skills.sshlg.me/skills/agent-sync/) · [follow @sshlg93 on X](https://x.com/intent/follow?screen_name=sshlg93)
+
+Loads in **DeepSeek Harness** (`dsh`) with **no plugin to write**: it reads the
+Agent Skills standard directly, scanning `~/.agents/skills` — where `npx skills
+add` puts this pack — at rank 500.
 
 **Several coding agents, one repository, no collisions — and each one can see what the
 others are doing.**
@@ -444,6 +451,10 @@ and `.agent-sync/` if you want the project clean too.
 
 ## Develop and verify
 
+<!-- commands-run-in: a clone -->
+These run **in a clone of this repository**. The published npm package ships no
+`test/` directory, so from an install they are names, not commands.
+
 ```bash
 python3 test/validate.py             # manifests, version sync, no host/credential leaks
 python3 test/validate.py --self-test # the validator must still be able to fail
@@ -451,7 +462,7 @@ npm test                             # both of the above
 ```
 
 What ships: one skill (`agent-sync`), `scripts/agent_sync.py` (stdlib only), four hook
-scripts, the slash command, `agent-sync.schema.json`, and ten reference contracts the
+scripts, the slash command, `agent-sync.schema.json`, and eleven reference contracts the
 agent loads on their own trigger rather than by default:
 
 | Reference | Read it when |
@@ -459,6 +470,7 @@ agent loads on their own trigger rather than by default:
 | [`adapter-contract.md`](plugins/agent-sync/skills/agent-sync/references/adapter-contract.md) | adding or auditing a knowledge backend |
 | [`lease-protocol.md`](plugins/agent-sync/skills/agent-sync/references/lease-protocol.md) | changing acquisition, expiry, stealing or id allocation |
 | [`backend-outline.md`](plugins/agent-sync/skills/agent-sync/references/backend-outline.md) | making any Outline API call, or debugging one |
+| [`backend-notion.md`](plugins/agent-sync/skills/agent-sync/references/backend-notion.md) | making any Notion API call, or debugging one |
 | [`backend-fs.md`](plugins/agent-sync/skills/agent-sync/references/backend-fs.md) | running without a cloud backend, or explaining degraded mode |
 | [`pipeline-binding.md`](plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md) | wiring `pipeline.json`, or adding a stage hook |
 | [`hooks.md`](plugins/agent-sync/skills/agent-sync/references/hooks.md) | installing, debugging or removing the Claude Code hooks |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Let concurrent coding agents share one project without colliding — leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py",
+    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py && python3 test/hooks_session_test.py",
     "prepublishOnly": "python3 test/validate.py"
   },
   "publishConfig": {

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Coordination layer for multi-agent repositories — leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
     "name": "ssheleg",

package/plugins/agent-sync/hooks/session-start.sh

@@ -6,14 +6,36 @@ S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
 
 # Stamp who this session is, keyed by the process every command in it descends from.
-# A hook has CLAUDE_SESSION_ID in its environment and a plain shell command does not, so without
-# this a second session in the same checkout adopts the first one's identity: both acquire and
-# release as one run, and the lease stops separating the exact case it exists for. $PPID here is
-# the CLI process, which is the one ancestor every later command shares.
-if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+# Without this a second session in the same checkout adopts the first one's identity: both
+# acquire and release as one run, and the lease stops separating the exact case it exists for.
+# $PPID here is the CLI process, which is the one ancestor every later command shares.
+#
+# The id arrives on STDIN as JSON, the way every other hook here reads its payload -- see
+# guard.sh. This block used to require CLAUDE_SESSION_ID in the ENVIRONMENT and nothing else,
+# so on this machine it never ran once: measured 2026-08-25, `.agent-sync/sessions` had never
+# been created and the run-id map held a single `shared` key, which is the weak identity that
+# makes an expired lease unattributable and `reap` refuse it forever. A fallback that is always
+# taken is not a fallback.
+if [ -t 0 ]; then
+  payload=""                       # no stdin (invoked by hand) -- do not block on `cat`
+else
+  payload=$(cat 2>/dev/null || true)
+fi
+sid="${CLAUDE_SESSION_ID:-}"
+if [ -z "$sid" ] && [ -n "$payload" ]; then
+  sid=$(printf '%s' "$payload" | python3 -c '
+import json,sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+print(d.get("session_id") or "")
+' 2>/dev/null)
+fi
+if [ -n "$sid" ]; then
   d="$(git rev-parse --show-toplevel 2>/dev/null)/.agent-sync/sessions"
   if mkdir -p "$d" 2>/dev/null; then
-    printf '%s' "$CLAUDE_SESSION_ID" > "$d/$PPID" 2>/dev/null || true
+    printf '%s' "$sid" > "$d/$PPID" 2>/dev/null || true
     # forget the stamps of processes that are gone, so the directory cannot grow without bound
     for f in "$d"/*; do
       b="$(basename "$f")"

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.16.0"
+  version: "1.18.0"
   author: ssheleg
 ---
 
@@ -99,22 +99,25 @@ question gets asked and answered, once, and written down.
 **Ask the operator these two things in chat — do not guess, do not pick a default:**
 
 1. **Where should coordination state live?**
-   - a knowledge cloud (`outline`) — the shared record, awareness and board across
-     machines. **It does not decide leases**; nothing in it can (trap 1);
+   - a knowledge cloud — `outline`, hosted or self-hosted, or `notion` — the shared
+     record, awareness and board across machines. **Neither decides leases**; nothing
+     in either can (trap 1);
    - or local files (`fs`) — no credentials, and no visibility to an agent on another
      machine: no shared awareness, no cross-repo signals, no shared board.
 
    The lease is decided separately by `leaseBackend` (trap 2), and **`gated` follows that
    choice, never the record plane**. Report the guarantee you actually have, not the
    stronger one the record plane suggests.
-2. **If cloud: the instance URL.** The URL is configuration, not a secret, so you
-   may write it. The **token is not** — you never ask for it in chat, never read it
-   back, and never place it yourself.
+2. **If cloud: where.** Outline needs its instance URL; Notion needs the id of the page
+   the container goes under. Both are configuration, not secrets, so you may write them.
+   The **token is not** — you never ask for it in chat, never read it back, and never
+   place it yourself.
 
 Then run it with their answers:
 
 ```bash
 python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend outline --url https://<their-instance>
+python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend notion
 python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend fs
 ```
 
@@ -333,6 +336,7 @@ Each file is loaded on its own trigger, not by default.
 | `references/adapter-contract.md` | adding or auditing a knowledge backend — six primitives, the capability flags, an honest degradation path |
 | `references/lease-protocol.md` | changing acquisition, expiry, stealing or id allocation |
 | `references/backend-outline.md` | making any Outline API call, or debugging one |
+| `references/backend-notion.md` | making any Notion API call, or debugging one |
 | `references/backend-fs.md` | running without a cloud backend, or explaining degraded mode |
 | `references/pipeline-binding.md` | wiring `pipeline.json`, or adding a stage hook |
 | `references/hooks.md` | installing, debugging or removing the Claude Code hooks |

package/plugins/agent-sync/skills/agent-sync/references/backend-notion.md

@@ -0,0 +1,153 @@
+# Notion backend
+
+**Read this when** making any Notion API call or debugging one.
+
+## Contents
+
+- [Shape of the API](#shape-of-the-api)
+- [Capabilities](#capabilities)
+- [Primitive mapping](#primitive-mapping)
+- [Why generated pages are one code block](#why-generated-pages-are-one-code-block)
+- [Calling it without leaking the token](#calling-it-without-leaking-the-token)
+- [Rate limits](#rate-limits)
+- [Getting a token](#getting-a-token)
+- [Sharing the plane with another person](#sharing-the-plane-with-another-person)
+- [Verifying access](#verifying-access)
+
+
+[Notion](https://www.notion.so) is single-tenant SaaS. There is no instance URL to
+configure and none to leak: every client talks to the same host, which is why
+`api.notion.com` is a constant in this code and Outline's address is not.
+
+## Shape of the API
+
+- Base: `https://api.notion.com/v1`. Methods are the ordinary ones — `GET` reads,
+  `POST` creates, `PATCH` appends and updates, `DELETE` removes.
+- `Authorization: Bearer <token>`, `Content-Type: application/json`, and
+  **`Notion-Version` is required**. This adapter pins `2026-03-11`; an unpinned client
+  gets whatever is current on the morning a breaking change ships.
+- Errors are unenveloped: the HTTP status is the status, and the body carries
+  `{"code": "...", "message": "..."}`. The codes that matter here are
+  `rate_limited` (429), `service_overload` (529) and **`conflict_error` (409)**.
+
+## Capabilities
+
+```json
+{ "atomicAppend": true, "totalOrderRead": true, "search": true }
+```
+
+`atomicAppend` is true because `PATCH /v1/blocks/{id}/children` is documented as
+"creates and appends new children blocks to the parent block_id specified", appended
+"to the end of the parent block's children" by default. There is no read-modify-write
+anywhere in the adapter, which is the whole of what the flag claims.
+
+**`exclusiveLease` is false, and no measurement can move it.** Notion has no
+compare-and-swap: nothing in the API lets a writer say *only if the page is still at
+the revision I read*. The endpoint documents `conflict_error` for two writers
+colliding, which is a retry hint, not an arbiter. Exclusion stays with `leaseBackend`
+— see `lease-protocol.md`.
+
+**These flags come from a measurement, not from the paragraph above.**
+`test/notion_live_test.py` is that measurement, and it passed against a live workspace on
+2026-08-25: 200 appends from two processes left 200 lines on one page, two independent
+reads returned one order, and two freshly created shards were both enumerated. Re-run it
+after any change to this adapter. The equivalent trap on Outline returned twelve successes
+for twelve concurrent appends and left three lines, which is why this is measured rather
+than read off the endpoint's documentation.
+
+**One thing the measurement is not allowed to test**, because the protocol never does it:
+two runs calling `tree.ensure` on the SAME title at once. The check-then-create races and
+both win a page of that name — observed, 100 lines on one and 100 on the other, both
+writers exiting 0. `Sync.log_id()` gives every run its own shard for exactly this class of
+reason, so the contention case is handed a page id instead.
+
+## Primitive mapping
+
+| Primitive | Call | Body |
+|---|---|---|
+| `tree.ensure` (container) | `POST /v1/pages` | `{parent: {page_id}, properties: {title}}` — `bootstrap` creates it once |
+| `tree.ensure` (document) | list children, else `POST /v1/pages` | matched on `child_page.title`, never on search |
+| `log.append` | `PATCH /v1/blocks/{id}/children` | one `paragraph` block per line |
+| `log.read` | `GET /v1/blocks/{id}/children` | cursor-paginated; join each block's text with a newline |
+| `doc.put` | `PATCH /v1/blocks/{block_id}` | one `code` block, replaced wholesale |
+| `doc.get` | `GET /v1/blocks/{id}/children` | the `code` block's text |
+| `search` | `POST /v1/search` | `{query, page_size}` |
+
+**Shards are enumerated by structure, never by search.** Notion's search index is
+eventually consistent, so a page it has not indexed yet reads as a page that does not
+exist — and a run that cannot see the other shards replays only its own and concludes
+it won. Outline paid for this lesson with eight processes and eight winners; the
+listing endpoint returns a page the moment it is created.
+
+Two hard limits: **100 children per append request**, and **2000 characters per
+rich-text item**. Lines are chunked below the second, at 1900.
+
+## Why generated pages are one code block
+
+The obvious `doc.put` — delete every child, append the new ones — costs one request
+per existing block. At three requests a second a regenerated board takes minutes, and
+the board is regenerated often. A single `code` block is two requests whatever the
+size, and it also stops the Notion editor from reinterpreting generated markdown as
+Notion formatting.
+
+## Calling it without leaking the token
+
+`curl -H "Authorization: Bearer $TOKEN"` puts the credential in `argv`, where every
+other process on the machine can read it. Use a config file on stdin — `--config -`
+reads the whole request description from a heredoc, so neither the token nor the
+payload appears in the process table.
+
+**Prefer the bundled `scripts/agent_sync.py`.** It calls the API through `urllib`
+inside its own process — no subprocess, no `argv`, nothing for another process to read.
+
+## Rate limits
+
+Two of them, and the second is the one that surprises people:
+
+- **Per connection** — an average of three requests per second, with some burst.
+- **Per workspace** — shared across every connection in it, scaled to the plan.
+
+Either returns `rate_limited` / 429 with `additional_data.rate_limit_reason` naming
+which one; 529 `service_overload` means Notion itself is having a minute. Both carry
+`Retry-After` in integer seconds. Honour it, back off exponentially, at most five
+attempts, then fail loudly. Do not spin.
+
+Because the second limit is shared, **a rate limit here is not necessarily your own
+traffic** — another script or another person in the same workspace can spend it. The
+adapter says so in its message rather than blaming the caller.
+
+## Getting a token
+
+A personal access token from Notion's developer portal — Personal access tokens →
+New token. It begins `ntn_`. No integration and no page-sharing dance is required:
+the token acts as the person who made it.
+
+```
+AGENT_SYNC_NOTION_TOKEN=<created by the operator, pasted by the operator>
+AGENT_SYNC_NOTION_PARENT=<the 32-character id ending the parent page's URL>
+AGENT_SYNC_NOTION_COLLECTION=<container page id, printed by `bootstrap`>
+```
+
+The operator creates it and pastes it themselves. Do not ask for the value in chat,
+do not read it back, and do not write it anywhere in the repository.
+
+## Sharing the plane with another person
+
+This is the reason the backend exists. Each person uses **their own** token; what
+they share is the container page. Share it in Notion the ordinary way, and every
+holder of a token that can see that page reads the same plane.
+
+What that does **not** give you is a shared lease: the plane carries the record and
+the awareness, and `leaseBackend` decides exclusion. Two people on two machines want
+`leaseBackend: "git"`, whose non-fast-forward rejection is a real compare-and-swap.
+
+## Verifying access
+
+```bash
+python3 scripts/agent_sync.py check
+```
+
+The preflight calls `GET /v1/users/me` — one request, no writes — and then resolves
+the container id. A `401` means the token is wrong or revoked, and retrying with the
+same one will not help. An `object_not_found` on the container means the token cannot
+see that page: share the page with the person whose token it is.

package/plugins/agent-sync/skills/agent-sync/scripts/agent_sync.py

@@ -33,7 +33,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.16.0"
+VERSION = "1.18.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -489,6 +489,23 @@ class Adapter:
     name = "none"
     capabilities = {"atomicAppend": False, "totalOrderRead": False, "search": False,
                     "exclusiveLease": False}
+    # What must be in the environment before this adapter can reach anything, and the
+    # variable holding its container id. Declared here so `check` and `status` ask the
+    # adapter instead of carrying a per-backend branch each — the shape that let the
+    # Outline credential check live in one place and be missing from the other.
+    REQUIRED_ENV: tuple[str, ...] = ()
+    COLLECTION_ENV = ""
+
+    def preflight(self) -> str:
+        """One cheap live call proving the credential works, or "" for none.
+
+        `check` used to report "knowledge base reachable" after a call that only
+        parsed a string. A check that reports reachability without reaching is the
+        defect class this whole suite exists to refuse."""
+        return ""
+
+    def create_container(self, name: str) -> str:
+        raise Fail(f"backend '{self.name}' has no container to create")
 
     def configured(self) -> bool:
         raise NotImplementedError
@@ -531,6 +548,8 @@ class OutlineAdapter(Adapter):
     """
 
     name = "outline"
+    REQUIRED_ENV = ("AGENT_SYNC_OUTLINE_URL", "AGENT_SYNC_OUTLINE_TOKEN")
+    COLLECTION_ENV = "AGENT_SYNC_OUTLINE_COLLECTION"
     # exclusiveLease is FALSE and that is not a formality. Outline has no
     # compare-and-swap, so a decision cannot be made after all contenders have
     # written — only after a settle window that is long enough in practice. Two runs
@@ -597,6 +616,16 @@ class OutlineAdapter(Adapter):
                 raise Fail(f"outline {endpoint}: cannot reach the instance ({exc.reason})") from exc
         raise Fail(f"outline {endpoint}: gave up after 7 attempts")
 
+    def preflight(self) -> str:
+        self.resolve_collection()
+        return "knowledge base reachable and the collection resolves"
+
+    def create_container(self, name: str) -> str:
+        data = self._call("collections.create", {"name": name, "description":
+                                                 "Coordination plane for agent-sync. Generated pages "
+                                                 "are stamped; edit sources in git."})
+        return str(data["id"])
+
     def resolve_collection(self) -> str:
         """Accept a UUID, a urlId, or the whole `name-urlId` slug from the browser.
 
@@ -698,7 +727,11 @@ class OutlineAdapter(Adapter):
 
 
 class FsAdapter(Adapter):
-    """Degraded mode. Files under .agent-sync/, committed and pushed.
+    """Degraded mode. Files under .agent-sync/, and NOT committed.
+
+    `check` refuses a tracked state directory — a committed run id hands this
+    checkout's identity to every clone, and the tree is dirty after every tool call.
+    This line claimed the opposite until 2026-08-25; the check was right.
 
     atomicAppend is FALSE on purpose: agents here are separated by git, not by a
     filesystem, so ordering is decided by a merge after the fact — which is not
@@ -767,10 +800,295 @@ class FsAdapter(Adapter):
         return [str(q) for q in sorted(self.base.glob(f"{stem}*.md"))]
 
 
+class NotionAdapter(Adapter):
+    """Notion. The container is a page, every log is a child page of it, and every
+    line is one paragraph block appended server-side.
+
+    The append is a real append: `PATCH /v1/blocks/{id}/children` "creates and appends
+    new children blocks to the parent block_id specified", at the end by default. There
+    is no read-modify-write anywhere in this class, which is what `atomicAppend` claims
+    and the only thing it claims.
+
+    `exclusiveLease` is FALSE and no measurement can change it: Notion has no
+    compare-and-swap. Two appends racing on one page can both succeed — the endpoint
+    documents `conflict_error` (409) for the case where they collide instead — so a
+    decision made by replaying this log is a decision made after the fact. Exclusion
+    stays with `leaseBackend`.
+    """
+
+    name = "notion"
+    REQUIRED_ENV = ("AGENT_SYNC_NOTION_TOKEN",)
+    COLLECTION_ENV = "AGENT_SYNC_NOTION_COLLECTION"
+    API = "https://api.notion.com/v1"
+    # Pinned, not floating. Notion versions its API by date and an unpinned client
+    # gets whatever is current the morning a breaking change ships.
+    NOTION_VERSION = "2026-03-11"
+    # One rich_text item caps at 2000 characters. Chunk below it rather than at it:
+    # a line that lands exactly on the boundary is the one that fails in production.
+    CHUNK = 1900
+    # The endpoint's own cap on children per request.
+    BATCH = 100
+
+    capabilities = {"atomicAppend": True, "totalOrderRead": True, "search": True,
+                    "exclusiveLease": False}
+
+    def __init__(self) -> None:
+        self.token = os.environ.get("AGENT_SYNC_NOTION_TOKEN") or ""
+        self.parent = os.environ.get("AGENT_SYNC_NOTION_PARENT") or ""
+        self.collection = os.environ.get("AGENT_SYNC_NOTION_COLLECTION") or ""
+        self._ids: dict[str, str] = {}
+
+    def configured(self) -> bool:
+        return bool(self.token and (self.collection or self.parent))
+
+    # -- transport ---------------------------------------------------------
+
+    @staticmethod
+    def _uuid(value: str) -> str:
+        """Accept what a person copies out of the address bar.
+
+        A Notion URL ends in 32 undashed hex characters; the API takes either form,
+        but a slug like `Board-1f2e…` does not resolve, so the digits are extracted
+        rather than assumed to be the whole string."""
+        raw = re.sub(r"[^0-9a-fA-F]", "", (value or "").rsplit("/", 1)[-1])
+        if len(raw) < 32:
+            raise Fail(f"'{value}' does not contain a 32-character Notion id — copy the "
+                       "page's URL and use the id at its end")
+        raw = raw[-32:].lower()
+        return f"{raw[0:8]}-{raw[8:12]}-{raw[12:16]}-{raw[16:20]}-{raw[20:32]}"
+
+    def _call(self, method: str, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        if not self.configured():
+            raise Fail("Notion is not configured (AGENT_SYNC_NOTION_TOKEN missing from "
+                       "the environment, or neither _COLLECTION nor _PARENT is set)")
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(f"{self.API}/{path}", data=data, method=method)
+        # The token reaches a header and nothing else — never a command line, never a
+        # log line, and never this module's error text.
+        req.add_header("Authorization", f"Bearer {self.token}")
+        req.add_header("Notion-Version", self.NOTION_VERSION)
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+
+        delay = 1.0
+        # Five attempts on a rate limit, then fail loudly — the contract's number,
+        # not a guess.
+        for attempt in range(5):
+            try:
+                with urllib.request.urlopen(req, timeout=20) as resp:
+                    return json.loads(resp.read().decode() or "{}")
+            except urllib.error.HTTPError as exc:
+                detail, code = "", ""
+                try:
+                    payload = json.loads(exc.read().decode())
+                    detail = payload.get("message") or ""
+                    code = payload.get("code") or ""
+                except (ValueError, OSError):
+                    pass
+                if exc.code in (401, 403):
+                    raise Fail(
+                        f"notion {method} {path}: {exc.code} — the token is rejected"
+                        f"{': ' + detail if detail else ''}. A credential does not "
+                        "become valid on retry.") from exc
+                # 429 and 529 carry Retry-After in integer seconds and mean *wait*.
+                # 409 conflict_error is two writers touching one page — the same
+                # answer, on a shorter clock. 5xx is the server's own bad minute.
+                if exc.code in (409, 429, 500, 502, 503, 504, 529) and attempt < 4:
+                    hint = exc.headers.get("Retry-After")
+                    time.sleep((float(hint) if hint else delay) + random.random() * 0.4)
+                    delay *= 2
+                    continue
+                reason = f"{code}: {detail}" if code and detail else (detail or code)
+                raise Fail(f"notion {method} {path}: HTTP {exc.code}"
+                           f"{' — ' + reason if reason else ''}") from exc
+            except urllib.error.URLError as exc:
+                if attempt < 2:
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+                raise Fail(f"notion {method} {path}: cannot reach the API "
+                           f"({exc.reason})") from exc
+            except TimeoutError as exc:
+                # A read that times out AFTER the connection is established raises this
+                # directly — `URLError` wraps only the connect failure — so it used to
+                # fall into the catch-all below and fail permanently on the first slow
+                # response. The contract calls a transport error retryable, and this is
+                # one. Measured 2026-08-25: a writer died mid-run with "The read
+                # operation timed out" while the workspace was under its own rate limit.
+                if attempt < 2:
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+                raise Fail(f"notion {method} {path}: the API did not answer within "
+                           f"{20}s, {attempt + 1} times over") from exc
+            except (ValueError, OSError) as exc:
+                raise Fail(f"notion {method} {path}: {exc}") from exc
+        raise Fail(f"notion {method} {path}: rate limited through 5 attempts — the "
+                   "workspace limit is shared by every connection in it, so this is "
+                   "not necessarily your own traffic")
+
+    # -- containers --------------------------------------------------------
+
+    def preflight(self) -> str:
+        self._call("GET", "users/me")
+        self.resolve_collection()
+        return "token accepted by Notion and the container id resolves"
+
+    def create_container(self, name: str) -> str:
+        if not self.parent:
+            raise Fail("AGENT_SYNC_NOTION_PARENT is not set — put the id of the page "
+                       "the container should live under in it. Copy the 32-character "
+                       "id from the end of that page's URL.")
+        page = self._call("POST", "pages", {
+            "parent": {"type": "page_id", "page_id": self._uuid(self.parent)},
+            "properties": {"title": {"title": [{"type": "text",
+                                                "text": {"content": name[:2000]}}]}},
+        })
+        return str(page["id"])
+
+    def resolve_collection(self) -> str:
+        if not self.collection:
+            raise Fail("AGENT_SYNC_NOTION_COLLECTION is not set — run `bootstrap` to "
+                       "create the container page, then put the id it prints into "
+                       f"{ENV_FILE}")
+        return self._uuid(self.collection)
+
+    def _children(self, oid: str) -> list[dict[str, Any]]:
+        """Every child block, followed to the last page.
+
+        Stopping at the first page would make a long log read as a short one, and a
+        short log replays into a wrong answer rather than an error."""
+        out: list[dict[str, Any]] = []
+        cursor = ""
+        while True:
+            q = f"blocks/{oid}/children?page_size=100" + (f"&start_cursor={cursor}" if cursor else "")
+            data = self._call("GET", q)
+            out.extend(data.get("results") or [])
+            if not data.get("has_more"):
+                return out
+            cursor = data.get("next_cursor") or ""
+            if not cursor:
+                return out
+
+    def tree_ensure(self, path: str) -> str:
+        if path in self._ids:
+            return self._ids[path]
+        collection = self.resolve_collection()
+        # Enumerate by STRUCTURE, never by the search index — Notion's search is
+        # eventually consistent, and a shard it has not indexed yet reads as a shard
+        # that does not exist. That is how eight processes each see only their own
+        # log and each conclude they won.
+        for block in self._children(collection):
+            if block.get("type") == "child_page" \
+                    and (block.get("child_page") or {}).get("title") == path:
+                self._ids[path] = block["id"]
+                return str(block["id"])
+        page = self._call("POST", "pages", {
+            "parent": {"type": "page_id", "page_id": collection},
+            "properties": {"title": {"title": [{"type": "text",
+                                                "text": {"content": path[:2000]}}]}},
+        })
+        self._ids[path] = page["id"]
+        return str(page["id"])
+
+    # -- logs --------------------------------------------------------------
+
+    def _rich(self, text: str) -> list[dict[str, Any]]:
+        parts = [text[i:i + self.CHUNK] for i in range(0, len(text), self.CHUNK)] or [""]
+        return [{"type": "text", "text": {"content": p}} for p in parts]
+
+    @staticmethod
+    def _text_of(block: dict[str, Any]) -> str | None:
+        """The literal text of a block, or None when it carries none.
+
+        `None` and `""` are different answers here: an empty paragraph is a line, and
+        a divider is not, and folding the two loses a line every time somebody presses
+        enter in the Notion editor."""
+        body = block.get(block.get("type") or "") or {}
+        rich = body.get("rich_text")
+        if not isinstance(rich, list):
+            return None
+        return "".join(r.get("plain_text") or (r.get("text") or {}).get("content") or ""
+                       for r in rich)
+
+    def log_append(self, oid: str, line: str) -> None:
+        self._call("PATCH", f"blocks/{oid}/children", {"children": [
+            {"object": "block", "type": "paragraph",
+             "paragraph": {"rich_text": self._rich(line.rstrip("\n"))}}]})
+
+    def log_read(self, oid: str) -> str:
+        lines = [t for t in (self._text_of(b) for b in self._children(oid)) if t is not None]
+        return "\n".join(lines) + ("\n" if lines else "")
+
+    # -- generated documents ----------------------------------------------
+
+    def doc_put(self, oid: str, text: str) -> None:
+        """Generated pages only, and they are ONE code block on purpose.
+
+        The obvious implementation — delete every child, append the new ones — costs
+        one request per existing block, and at three requests a second a regenerated
+        board would take minutes. A single block is two requests whatever the size."""
+        blocks = self._children(oid)
+        target = next((b for b in blocks if b.get("type") == "code"), None)
+        payload = {"rich_text": self._rich(text), "language": "markdown"}
+        if target:
+            self._call("PATCH", f"blocks/{target['id']}", {"code": payload})
+            return
+        for block in blocks:
+            self._call("DELETE", f"blocks/{block['id']}")
+        self._call("PATCH", f"blocks/{oid}/children",
+                   {"children": [{"object": "block", "type": "code", "code": payload}]})
+
+    def doc_get(self, oid: str) -> str:
+        blocks = self._children(oid)
+        target = next((b for b in blocks if b.get("type") == "code"), None)
+        if target is not None:
+            return self._text_of(target) or ""
+        return self.log_read(oid)
+
+    # -- search ------------------------------------------------------------
+
+    def search(self, query: str, limit: int = 10) -> list[dict[str, Any]]:
+        data = self._call("POST", "search", {"query": query, "page_size": max(1, min(limit, 100))})
+        out: list[dict[str, Any]] = []
+        for row in (data.get("results") or [])[:limit]:
+            title = ""
+            for prop in (row.get("properties") or {}).values():
+                if isinstance(prop, dict) and prop.get("type") == "title":
+                    title = "".join(t.get("plain_text") or "" for t in (prop.get("title") or []))
+                    break
+            out.append({"id": row.get("id"), "title": title, "snippet": ""})
+        return out
+
+    def log_shards(self, prefix: str) -> list[str]:
+        out: list[str] = []
+        for block in self._children(self.resolve_collection()):
+            if block.get("type") != "child_page":
+                continue
+            title = (block.get("child_page") or {}).get("title") or ""
+            if title.startswith(prefix):
+                out.append(str(block["id"]))
+                self._ids[title] = block["id"]
+        return out
+
+
+# Every backend that talks to a service, in ONE place. `check`, `init`'s argument
+# parser, `bootstrap` and `status` all read this dict rather than each carrying a copy
+# of the list — the copies are what drift, and a backend missing from one of them is a
+# backend that half exists.
+CLOUD_ADAPTERS: dict[str, type[Adapter]] = {
+    "outline": OutlineAdapter,
+    "notion": NotionAdapter,
+}
+BACKENDS = tuple(sorted(CLOUD_ADAPTERS)) + ("fs",)
+
+
 def make_adapter(cfg: dict[str, Any], root: Path) -> Adapter:
     backend = os.environ.get("AGENT_SYNC_BACKEND") or cfg.get("backend") or "fs"
-    if backend == "outline":
-        ad = OutlineAdapter()
+    cls = CLOUD_ADAPTERS.get(backend)
+    if cls is not None:
+        ad = cls()
         if not ad.configured():
             return FsAdapter(root)
         return ad
@@ -2374,7 +2692,11 @@ class Sync:
             return set()
         text = path.read_text()
         ids = set(re.findall(rf"\b{reg}-\d+\b", text))
-        pattern = spec.get("nextFreeIdPattern")
+        # Through the shim, not the raw key. Reading `nextFreeIdPattern` directly meant
+        # a config written with the modern `pattern` key never discarded its own
+        # next-free line, and the baseline was stamped one higher than reality —
+        # exactly what the docstring above warns about. Reproduced 2026-08-25.
+        pattern = id_pattern(spec)
         if pattern:
             m = re.search(pattern, text)
             if m:
@@ -2889,6 +3211,10 @@ def cmd_init(args: argparse.Namespace) -> int:
         extra = (f"AGENT_SYNC_OUTLINE_URL={args.url}\n"
                  "AGENT_SYNC_OUTLINE_TOKEN=\n"
                  "AGENT_SYNC_OUTLINE_COLLECTION=\n")
+    elif backend == "notion":
+        extra = ("AGENT_SYNC_NOTION_TOKEN=\n"
+                 "AGENT_SYNC_NOTION_PARENT=\n"
+                 "AGENT_SYNC_NOTION_COLLECTION=\n")
     env_path = root / ENV_FILE
     if env_path.exists() and not args.force:
         print(f"• {ENV_FILE} already exists — left untouched")
@@ -2902,7 +3228,25 @@ def cmd_init(args: argparse.Namespace) -> int:
     ensure_untracked(root, f"{STATE_DIR}/")
 
     print()
-    if backend == "outline":
+    if backend == "notion":
+        print("NEXT — three things only you can do:")
+        print("  1. Create a personal access token: Notion's developer portal →")
+        print("     Personal access tokens → New token. It begins `ntn_`.")
+        print("     Reference: https://developers.notion.com/docs/create-a-notion-integration")
+        print(f"  2. Put it, and the page the container should live under, in {ENV_FILE}:")
+        print("       AGENT_SYNC_NOTION_TOKEN=<paste it here>")
+        print("       AGENT_SYNC_NOTION_PARENT=<the 32-character id ending that page's URL>")
+        print("  3. Load the file into your shell before running agents:")
+        print(f"       set -a && . ./{ENV_FILE} && set +a")
+        print()
+        print("  Then run `bootstrap` — it creates the container page and prints the id")
+        print("  to paste into AGENT_SYNC_NOTION_COLLECTION. Share that page in Notion")
+        print("  with the other people working this repository; each of them uses their")
+        print("  OWN token, and yours stays yours.")
+        print()
+        print("  The lease is decided by `leaseBackend`, not by Notion — Notion has no")
+        print("  compare-and-swap. See references/backend-notion.md.")
+    elif backend == "outline":
         print("NEXT — two things only you can do:")
         print(f"  1. Create an API token in your Outline instance at {args.url}")
         print("     (Settings → API and access), then put it in this line of "
@@ -3005,8 +3349,8 @@ def cmd_status(_args: argparse.Namespace) -> int:
     elif not s.lease_is_cross_machine:
         print(f"  ({detail})")
 
-    if ad.name == "outline" and isinstance(ad, OutlineAdapter) and not ad.collection:
-        print("\n✗ AGENT_SYNC_OUTLINE_COLLECTION is empty.")
+    if ad.COLLECTION_ENV and not getattr(ad, "collection", ""):
+        print(f"\n✗ {ad.COLLECTION_ENV} is empty.")
         print("\nNEXT: create the container, then paste the id into "
               f"{ENV_FILE}:")
         print("  agent_sync.py bootstrap")
@@ -3166,20 +3510,26 @@ def pipeline_installed() -> bool:
 
 
 def cmd_bootstrap(_args: argparse.Namespace) -> int:
-    load_env_file(project_root())
-    ad = OutlineAdapter()
+    root = project_root()
+    load_env_file(root)
+    cfg_path = root / CONFIG_PATH
+    cfg = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+    backend = os.environ.get("AGENT_SYNC_BACKEND") or cfg.get("backend") or "fs"
+    cls = CLOUD_ADAPTERS.get(backend)
+    if cls is None:
+        raise Fail(f"backend '{backend}' has no container to create — `bootstrap` is "
+                   f"for {', '.join(sorted(CLOUD_ADAPTERS))}")
+    ad = cls()
     if not ad.configured():
-        raise Fail("set AGENT_SYNC_OUTLINE_URL and AGENT_SYNC_OUTLINE_TOKEN first")
-    if ad.collection:
-        print(f"collection already set: {ad.collection}")
+        raise Fail(f"set {' and '.join(cls.REQUIRED_ENV)} first")
+    if getattr(ad, "collection", ""):
+        print(f"container already set: {ad.collection}")
         return 0
     name = f"agent-sync — {repo_name()}"
-    data = ad._call("collections.create", {"name": name, "description":
-                                           "Coordination plane for agent-sync. Generated pages "
-                                           "are stamped; edit sources in git."})
-    print(f"✓ created collection '{name}'")
+    oid = ad.create_container(name)
+    print(f"✓ created container '{name}'")
     print(f"\nNEXT: put this in {ENV_FILE}:")
-    print(f"  AGENT_SYNC_OUTLINE_COLLECTION={data['id']}")
+    print(f"  {cls.COLLECTION_ENV}={oid}")
     return 0
 
 
@@ -4027,7 +4377,7 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
         raise Fail(f"{CONFIG_PATH} is not valid JSON: {exc}") from exc
     ok.append(f"config parses ({CONFIG_PATH})")
 
-    if cfg.get("backend") not in ("outline", "fs"):
+    if cfg.get("backend") not in BACKENDS:
         problems.append(f"backend '{cfg.get('backend')}' is not a known adapter")
     for k in sorted(set(cfg) - CONFIG_KEYS):
         problems.append(f"config key '{k}' is not in the schema — it will be ignored")
@@ -4142,20 +4492,19 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
         ok.append(f"credentials file in force: {env} (outside this repository)")
     elif env is not None:
         ok.append(f"credentials file in force: {env}")
-    if cfg.get("backend") == "outline":
+    cloud = CLOUD_ADAPTERS.get(cfg.get("backend") or "")
+    if cloud is not None:
         if env is None:
             problems.append(f"no {ENV_FILE} found here or in any parent — the backend "
                             "cannot be reached, and every run silently degrades")
         else:
             ok.append(f"credentials file found at {env}")
-            missing = [k for k in ("AGENT_SYNC_OUTLINE_URL", "AGENT_SYNC_OUTLINE_TOKEN")
-                       if not os.environ.get(k)]
+            missing = [k for k in cloud.REQUIRED_ENV if not os.environ.get(k)]
             if missing:
                 problems.append(f"{', '.join(missing)} is empty — runs will degrade to `fs`")
             else:
                 try:
-                    OutlineAdapter().resolve_collection()
-                    ok.append("knowledge base reachable and the collection resolves")
+                    ok.append(cloud().preflight() or f"{cloud.name}: credentials present")
                 except Fail as exc:
                     problems.append(f"knowledge base unreachable: {exc}")
 
@@ -4467,7 +4816,7 @@ def build_parser() -> argparse.ArgumentParser:
     sub = p.add_subparsers(dest="cmd", required=True)
 
     i = sub.add_parser("init", help="ask where to store, write config and env file")
-    i.add_argument("--backend", required=True, choices=["outline", "fs"])
+    i.add_argument("--backend", required=True, choices=list(BACKENDS))
     i.add_argument("--url", help="instance URL (required for outline)")
     i.add_argument("--force", action="store_true")
     i.set_defaults(fn=cmd_init)