@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/docs/coordinator-hook.md

@@ -0,0 +1,211 @@
+# coordinator-hook
+
+`pa-coordinator-hook` — a Claude Code `PreToolUse` hook that mechanically
+enforces a three-tier tool policy on interactive PA main threads: dispatch
+primitives are always allowed, a small argument-gated set of Bash/Read/Write
+calls are permitted for coordination-scale work, and everything else
+(`Edit`, `Grep`, `WebFetch`, …) is blocked with a message pointing at the
+dispatch alternative.
+
+This exists because "handle it inline instead of dispatching" is a repeat
+failure mode for interactive PAs — soft discipline in CLAUDE.md isn't
+sufficient on its own. See `projects/agentic-harness/product-vision.md` §1
+item 6 for the design rationale (operator repo, not this one).
+
+## Status
+
+Implemented: full three-tier decision engine, config + per-PA overlay
+loading, `--help`. Not yet wired into any `~/.claude/settings.json` by this
+package — that's an explicit boundary (see below), and the `pa-init`
+scaffold does not yet emit the snippet either (tracked as a follow-up, not
+done in the PR that introduced this doc).
+
+## How it works
+
+Claude Code's `PreToolUse` hook contract (verified against the current docs
+at the time this was built —
+[code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)):
+every `PreToolUse` invocation matching the configured `matcher` gets the
+event as JSON on **stdin** (not an env var — the `TOOL_NAME` env var
+mentioned in some older mental models of this contract does not exist in
+the current shape):
+
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": { "command": "npm test" },
+  "cwd": "/home/user/my-project",
+  "session_id": "...",
+  "permission_mode": "default"
+}
+```
+
+Exit codes: `0` = allow (falls through to Claude Code's normal permission
+flow — the hook only ever *tightens*, it never auto-grants), `2` = block
+(stderr becomes the message the model sees), anything else = non-blocking
+error (tool call proceeds; stderr is logged to the transcript). `pa-
+coordinator-hook` uses exit `1` for a malformed/empty stdin payload — it
+fails OPEN on hook-input errors rather than blocking every tool call
+estate-wide because of a hook bug.
+
+## The three tiers
+
+**Tier 1 — always allowed, never reaches the hook.** Dispatch + coordination
+primitives (`Agent`, `SendMessage`, `TaskCreate`, `Skill`, …). The
+settings.json `matcher` (below) simply never fires the hook for these tool
+names, so there's no tier1 enforcement code — `config.tier1` in
+`coordinator-allowlist.json` is documentation only.
+
+**Tier 2 — argument-gated allowlist.** `Bash`, `Read`, `Write`. The hook
+inspects `tool_input` against regex allow patterns:
+
+- **Bash** — `command` must match one of `tier2.Bash.allowPatterns` (`pa `,
+  `desk `, `git status`, `gh api `, `ls`, …), and must NOT match
+  `hardDeny.bashPatterns` or contain a shell-chaining metacharacter
+  (`;`, `&&`, `||`, `|`, `` ` ``, `$(`) — the chain-guard exists so a command
+  like `pa knowledge search foo && rm -rf ~` can't slip through on the
+  strength of its allowed prefix.
+- **Read** — `file_path` must match `tier2.Read.allowPathPatterns` (repo-
+  relative: `.session/`, `agents/<self>/`, `work/`, `projects/*/project.json`,
+  …) or `allowAbsolutePathPatterns` (`/tmp/`, `/private/tmp/` — scratchpad),
+  and must NOT match `blockPathPatterns` (`operator/knowledge/**` — direct
+  reads bypass the knowledge graph; use `pa knowledge` verbs instead) or
+  `hardDeny.pathPatterns` (`.ssh/`, `.vault/`, `secrets.enc.json`, `.env` —
+  credential material, never overridable by an overlay).
+- **Write** — same shape as Read, no `blockPathPatterns` (default-deny
+  already covers "anything not explicitly staged/session/cache/scratch").
+
+`<self>` in a path pattern is substituted at runtime: the resolved `paName`
+(`PA_SELF_AGENT` env var, else `operator/config/preferences.json#paName`
+read relative to the resolved repo root) when known, else `[^/]+` — the
+documented fallback ("if unknown, allow any `agents/*/` path").
+
+**Tier 3 — always blocked.** `Edit`, `NotebookEdit`, `Grep`, `Glob`,
+`WebFetch`, `WebSearch`. Every invocation gets a tool-specific message
+(`config.messages[toolName]`) pointing at the dispatch alternative — e.g.
+Grep says "dispatch Explore for search", WebFetch says "dispatch
+`/research`".
+
+### Hard-deny (never overridable by an overlay)
+
+`hardDeny` in `coordinator-allowlist.json` is checked before any allow
+pattern, core or overlay-supplied, for both Bash commands and Read/Write
+paths. It exists because the overlay mechanism (below) only *adds* allow
+patterns — a careless or malicious overlay entry (e.g. an allow pattern that
+accidentally matches `rm -rf ~` because it was written too loosely) must not
+be able to defeat the policy's basic safety floor. Covers: `rm -rf`,
+`curl | sh` / `wget | sh`, `git push --force`, `git reset --hard`,
+`git clean -f`, `git branch -D`, `--no-verify`, `--no-gpg-sign`,
+`gh repo delete` and other destructive `gh` verbs, `sudo`, `dd if=`,
+`mkfs`, raw-disk redirects, and reads/writes of `.ssh/`, `.aws/`,
+`.vault/`, `secrets.enc.json`, `.env`. Not a security sandbox — a
+determined caller can still construct a bypass a naive prefix/negative-list
+regex won't catch — just a mechanical backstop against the obviously
+destructive cases.
+
+## Toggle
+
+```sh
+PA_COORDINATOR_MODE=1   # enforce
+# unset, or anything other than "1"                → transparent no-op, exits 0 for everything
+```
+
+Deliberately a different variable name from the unofficial internal
+`CLAUDE_CODE_COORDINATOR_MODE` some environments may already use — this one
+is owned by the pa-coordinator-hook contract specifically.
+
+## Config
+
+Core allowlist ships at `packages/cli/config/coordinator-allowlist.json`
+(bundled into the published tarball at
+`dist/engineering-pa-cli/config/coordinator-allowlist.json` — resolved via
+`import.meta.url` at runtime, so it works identically from source and from
+the bundled package). **This file is not the place to add a personal
+exception** — it ships inside the package and is overwritten on every
+`pnpm add`/upgrade.
+
+### Per-PA overlay
+
+Add allow-pattern exceptions at:
+
+- `~/.claude/coordinator-overlay.json` (home — applies to every repo on the
+  machine), and/or
+- `<repo-root-or-cwd>/.claude/coordinator-overlay.json` (workspace —
+  applies to just this operator repo; applied after the home overlay, so it
+  can extend past whatever the home overlay already added)
+
+```jsonc
+{
+  "tier2": {
+    "Bash": { "allowPatterns": ["^npm ls\\s"] },
+    "Read": { "allowPathPatterns": ["^docs/"] }
+  }
+}
+```
+
+**Contract (enforced by `mergeOverlay` in `config.mjs`):** an overlay may
+ONLY extend `tier2.<Bash|Read|Write>.allowPatterns` /
+`.allowPathPatterns`. It cannot move a tool between tiers, touch
+`tier1`/`tier3`, or touch `hardDeny` — any other key is ignored and reported
+as a stderr warning, never silently accepted. This is deliberate: silently
+accepting an unrecognised overlay shape is exactly how a stray key would
+quietly widen the policy.
+
+## Settings snippet (documentation only — not applied by this package)
+
+Wire the hook up in your OWN `~/.claude/settings.json` (per-machine operator
+territory — this package never writes to it):
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Bash|Read|Write|Edit|NotebookEdit|Grep|Glob|WebFetch|WebSearch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pa-coordinator-hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Then, per-repo or per-session:
+
+```sh
+export PA_COORDINATOR_MODE=1
+```
+
+## Verifying an install
+
+```sh
+pa-coordinator-hook --help                # prints usage, exits 0
+
+# allow (mode off — transparent no-op)
+echo '{"tool_name":"Grep","tool_input":{}}' | pa-coordinator-hook; echo $?   # 0
+
+# block (mode on, tier3)
+echo '{"tool_name":"Grep","tool_input":{}}' \
+  | PA_COORDINATOR_MODE=1 pa-coordinator-hook; echo $?                       # 2
+
+# allow (mode on, tier2 Bash allow pattern)
+echo '{"tool_name":"Bash","tool_input":{"command":"pa knowledge search foo"}}' \
+  | PA_COORDINATOR_MODE=1 pa-coordinator-hook; echo $?                       # 0
+```
+
+## Known follow-ups (not done in this package)
+
+- **`/research` light mode** (operator-side skill, not this package) runs
+  inline `WebFetch`/`WebSearch` — under coordinator mode that path is
+  blocked. The skill needs to detect `PA_COORDINATOR_MODE=1` and switch
+  light-mode to a scoped dispatch. Tracked as a separate work item — not
+  changed here.
+- **`pa-init` scaffold** does not yet emit the settings.json snippet or a
+  starter `.claude/coordinator-overlay.json` for new operator repos.
+- **`gh` verb allowlist** is coarse (`gh api ` allows any subpath, `gh pr
+  {view,list,merge,close}`) — if a narrower per-repo policy is needed later,
+  extend via overlay rather than editing the core config.

package/dist/engineering-pa-cli/docs/estate-sync.md

@@ -0,0 +1,412 @@
+# estate-sync
+
+`ai.stravica.ops.estate-sync` — single-writer-per-host git sync for
+ESTATE-NATIVE content only.
+
+The sole git-writer on a host running HQ scheduled tools, for the paths
+this tool actually owns. Cron tools (distill, wsd-ingest,
+upstream-triage, …) become pure file writers; this tool is the one
+process per host that ever `git add` / `git commit` / `git push`. That
+structural rule eliminates the intra-host write race that previously
+caused `fail-rebase` and `fail-dirty-tree` cron alerts.
+
+**Renamed from `dave-sync`** (library-sync-solidification, D1). The
+rename is not cosmetic: the rewrite that ships alongside it replaces a
+blind `git add -A` with a REGISTRY-SCOPED commit set. Task/schedule ids
+that reference this tool by its estate-side name (e.g.
+`schedules/dave-sync.json`) are estate data, out of scope for this
+package — they don't need to change for the tool to work; the bin alias
+below covers that gap during migration.
+
+## Status
+
+Implemented: `run`, `run --dry-run`, `--help`.
+
+## Install / invoke
+
+```
+estate-sync run
+estate-sync run --dry-run
+estate-sync --help
+```
+
+`sync` is kept as a back-compat alias — identical bin, identical
+behaviour, same entry point (`src/sync/cli.mjs`). Existing crontab /
+schedule entries invoking `sync run` keep working unchanged; new installs
+should prefer `estate-sync run`.
+
+Designed to run every 30 minutes on each HQ host (smarthome01 + optional
+macbook). The companion schedule definition is at
+`schedules/dave-sync.json` (operator instance) — renaming that schedule
+id/tag is estate-side work, not part of this package.
+
+## Commands
+
+### `estate-sync run`
+
+1. **Acquire process lock.** A PID file at `<repoRoot>/.cache/estate-sync/.lock`
+   ensures no two sync runs overlap on a host. The lock is considered
+   stale after 10 minutes (a real run never legitimately takes that long;
+   the cron tick is 30 minutes, so a 10-minute window is safely under
+   the next-tick interval). On lock contention the run exits 0 with
+   status `noop-locked`; the next tick retries.
+2. **`git fetch origin`.** Refresh remote-tracking refs **before** the
+   ahead/behind probe so the short-circuit in step 4 sees what origin
+   actually has. Without this, a long-idle clean clone computes
+   `behind` from whatever `origin/<branch>` happened to point at on
+   the last successful fetch — which can be days stale, and the
+   noop short-circuit then traps the clone on stale state forever.
+   Fetch failure (network / auth) is logged but **not blocking**: the
+   sync continues on stale refs for this tick, which still allows
+   local-only commits to be made and queued for push; the next tick
+   retries. Skipped under `--dry-run` to preserve the "no git commands
+   spawned" contract.
+3. **Examine state.** `git status --porcelain` to detect a dirty working
+   tree; `git rev-list --left-right --count HEAD...@{u}` to detect local
+   commits ahead of (or behind) origin.
+4. **Short-circuit if nothing to do.** Clean tree + 0 ahead + 0 behind
+   ⇒ exit 0, status `noop-nothing-to-do`. (Accurate now that step 2
+   refreshes the refs.)
+5. **Compose commit body + compute commit scope.** Walk
+   `.cache/*/logs/runs.jsonl` and `operator/extensions/tools/*/logs/runs.jsonl`
+   for the runs-digest section of the commit body (see `runs-digest.mjs`).
+   In parallel, compute the registry-scoped commit-scope decision (see
+   below) — cheap, at most two small JSON reads.
+6. **Stage — registry-scoped, never a blind `git add -A`.**
+
+   When `<repoRoot>/operator/registry/{devices.json,repos.json}` both
+   exist:
+   - Resolve this device from `os.hostname()` against `devices.json`
+     (exact host match, then device-id-equals-hostname, then
+     short-name-before-first-dot — identical algorithm to
+     `operator/extensions/tools/library-sync/run.mjs`'s
+     `resolveDeviceId`, so the two tools never disagree about "which
+     device am I").
+   - Resolve the repos this device is entitled to
+     (`devices.json[deviceId].entitlements.repos`).
+   - Derive the EXCLUSION set: every entitled repo's mount `to` subtree,
+     **unconditionally** (no ownership carve-out — see
+     `registry-scope.mjs`'s module doc for why this is deliberately
+     simpler than library-sync's own down-path owner-exclusion), plus
+     `.vault/**` unconditionally.
+   - Stage ONLY the in-scope dirty paths (everything from
+     `git status --porcelain` NOT under an excluded subtree) via
+     explicit pathspecs: `git add -- <path> <path> ...`. An untracked
+     file inside an excluded subtree is never passed to `git add`, so it
+     can never be staged — the pathspec approach handles this by
+     construction, not by a follow-up filter.
+
+   When the registry is **not present** at this repo root: previous
+   (pre-rewrite) behaviour — unscoped `git add -A` — but LOUDLY flagged,
+   both in the run's stderr output and in the commit body
+   (`estate-sync: no registry found, unscoped commit`).
+
+   Either way, the commit body gets a scope-decision section reporting
+   counts: paths staged, subtrees excluded by rule (see "Commit body"
+   below).
+7. **`git commit -m "estate-sync <ISO ts>" -m "<body>"`.** Commit
+   **before** the rebase. `git pull --rebase` refuses to run when the
+   index or working tree has uncommitted changes, so the working state
+   must be turned into a real commit first. Skipped if the tree is
+   clean (e.g. a `behind`-only state — the pull is the whole job), or if
+   every dirty path was excluded by the commit scope (nothing staged).
+8. **`git pull --rebase origin <branch>`.** Fetch was done in step 2,
+   so this is just the rebase. Now safe because the index is clean
+   (we either committed in step 6/7 or the tree was already clean).
+   Skipped entirely if step 2's fetch failed (rebasing onto stale
+   refs is a no-op at best and a spurious failure at worst).
+
+   **Conflict handling (auto-resolve on regenerated artifacts).** When
+   the rebase conflicts, sync checks whether every conflicted path is
+   in the *regenerated-artifacts allowlist* (see below). Files in that
+   list are regenerated by distillation on every host — different byte
+   output, semantically-equivalent content — so a conflict is a race
+   between two hosts' regenerations, not a real disagreement. In that
+   case sync takes origin's version (`git checkout --ours -- <paths>`;
+   note the rebase-inversion — `--ours` refers to the branch being
+   rebased *onto*), stages the paths, `git rebase --continue`s, and
+   proceeds to push. The audit record adds
+   `autoResolved: <N>` + `autoResolvedPaths: [...]` to the `ok` line.
+
+   If **any** conflicted path is outside the allowlist,
+   `git rebase --abort` runs and sync exits 2 with status `fail-rebase`
+   as before. Real content conflicts still surface for human resolution;
+   the audit record includes `conflictedPaths: [...]` for the disallowed
+   paths so the on-call has a starting point.
+
+### Registry-scoped commit set
+
+Source: `src/sync/registry-scope.mjs`. Pure functions over injected
+registry docs + `os.hostname()` — no git, no spawning, fully unit-tested
+in isolation from `run.mjs`.
+
+Degrade-gracefully-never-crash contract, in priority order:
+
+1. `operator/registry/devices.json` or `repos.json` missing at this repo
+   root → `registryPresent: false` (unscoped fallback).
+2. Either file present but unparseable JSON → `registryPresent: false`,
+   with a warning naming the parse failure (unscoped fallback).
+3. Registry present and parseable, but this device's hostname doesn't
+   resolve to a known device id → `registryPresent: false`, warning
+   naming the hostname tried (unscoped fallback).
+4. Otherwise → `registryPresent: true`, scoped exclusion set computed.
+
+None of these paths ever throws out of `computeCommitScope` — a broken
+or absent registry degrades to the pre-rewrite behaviour, never a crashed
+30-minute cron.
+
+### Regenerated-artifacts allowlist
+
+Built-in defaults (in `src/sync/regenerated-artifacts.mjs`):
+
+- `operator/knowledge/.graph.json`
+- `operator/knowledge/.backlinks.json`
+- `operator/knowledge/domains.json`
+- `operator/profile/profile.md`
+- `operator/profile/operator.json`
+- `operator/knowledge/systems/web-properties/*.md`
+
+Repos can extend the allowlist by adding `<repoRoot>/.sync-config.json`:
+
+```json
+{
+  "regeneratedArtifacts": [
+    "projects/foo/generated.json",
+    "some/tool/output/**/*.json"
+  ]
+}
+```
+
+Entries are additive to the defaults. Globs use POSIX-style `*`
+(single segment) and `**` (any number of segments) via
+`node:path.matchesGlob`. Missing / malformed config file falls back to
+defaults with a stderr warning; the config is intentionally non-fatal
+so an editor mistake can't wedge the cron.
+
+9. **`git push`.** On rejection: `git fetch && git pull --rebase` and
+   retry the push once. If the retry fails, exit 2 with status
+   `fail-push` and leave the commit local (next tick will reconcile or
+   surface again).
+10. **Append audit record** to `<repoRoot>/.cache/estate-sync/logs/runs.jsonl`.
+
+### `estate-sync run --dry-run`
+
+Same as steps 1–5 (lock is still taken — dry-run still serialises
+against itself), then prints the would-be commit title, body, and scope
+decision, and exits 0. Never spawns `git add`/`commit`/`push`, never
+writes `runs.jsonl`.
+
+### Commit body
+
+Two sections, in order:
+
+1. **Scope-decision section** — either:
+   - `estate-sync scope: registry-scoped (device=<id>)` with `staged: N
+     path(s)` and `excluded: M subtree(s) by rule (K dirty path(s)
+     matched) — <list>`, or
+   - `estate-sync: no registry found, unscoped commit` (the loud
+     unscoped-fallback flag).
+2. **Runs-digest section** — the pre-existing per-cron-tool summary
+   (unchanged; see `runs-digest.mjs`).
+
+### `runs.jsonl` audit-record schema
+
+One JSON object per line, camelCase keys (§11 of the tooling standard):
+
+| Field | Type | Description |
+|---|---|---|
+| `ts` | string | RFC-3339 / ISO-8601 UTC timestamp. Round-trips through `new Date()`. |
+| `status` | string | Semantic status, closed vocabulary (see below). |
+| `exitCode` | number | Process exit code (0 / 2 / 3). |
+| `durationSec` | number | Seconds elapsed since start of run. |
+| `reason` | string | Present on every non-`ok`/non-`noop-nothing-to-do` record; omitted otherwise. |
+| `dirty` | bool | Working tree was dirty at examine-time. `noop-nothing-to-do` only. |
+| `ahead` | number | Local commits ahead of origin. `noop-nothing-to-do` only. |
+| `behind` | number | Origin commits the local branch is behind. `noop-nothing-to-do` only. |
+| `committed` | bool | A commit was created this run. `ok` only. |
+| `pushed` | bool | A push succeeded this run. `ok` only. |
+| `retriedAfterRebase` | bool | The push needed a rebase + retry. `ok` only. |
+| `branch` | string | The current branch name. Present on `ok` and `noop-nothing-to-do`. |
+| `autoResolved` | number | Number of allowlisted regenerated-artifact paths auto-resolved during a rebase conflict. `ok` only, present iff > 0. |
+| `autoResolvedPaths` | string[] | The specific paths that got the `--ours` treatment. `ok` only, paired with `autoResolved`. |
+| `conflictedPaths` | string[] | The disallowed conflicted paths that forced the abort. `fail-rebase` only, when at least one conflict was outside the allowlist. |
+
+Status vocabulary (closed set):
+
+| Status | exitCode | When |
+|---|---|---|
+| `ok` | 0 | Commit + push (or pull-only) succeeded. |
+| `noop-nothing-to-do` | 0 | Clean tree, no local commits ahead, up-to-date with origin. |
+| `noop-locked` | 0 | Another sync run holds the lock. |
+| `fail-rebase` | 2 | `git pull --rebase` conflicted; rebase aborted. Human reconciliation required. |
+| `fail-push` | 2 | Push rejected even after one rebase-and-retry. Commit is local-only. |
+| `fail-git` | 3 | A `git status`/`add`/`commit` command itself errored (transport or IO). |
+| `fail-cli-bootstrap` | varies | parseArgs / import / startup failure before runSync was reached. |
+
+Consumer contract: monitors should treat `status == 'ok'` and any
+`noop-*` as healthy; any `fail-*` as failing.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | OK — nothing to do, or sync completed and (optionally) pushed. |
+| `1` | Usage error (unknown verb, bad flag). |
+| `2` | Logical / operational failure (rebase conflict, push rejected after retry). |
+| `3` | Transport / IO failure (a git command itself errored). |
+
+## Operational discipline rules
+
+1. **Single writer per host, for the paths it owns.** This tool is the
+   only HQ process that performs `git add` / `git commit` / `git push`
+   on the shared estate repo. It is scoped to estate-native content —
+   mount-owned paths, `agents/*` run-state, and `.vault/**` ride the
+   library pipeline instead (see the library-sync-solidification
+   architecture decision, D1/D2). Cron tools (`distill`, `wsd-ingest`,
+   `upstream-triage`) write files only. The chokepoint is the lock file
+   plus the discipline that no other tool spawns mutating git commands.
+2. **Never a blind `git add -A` when a registry is present.** Explicit
+   pathspecs only. The no-registry fallback IS still `git add -A`, by
+   design (nothing to scope against) — but it is loud about it in both
+   the run's output and the commit body, never silent.
+3. **No shell interpolation.** Every spawn passes arguments as an array
+   with `shell:false`. Commit message bodies (which can contain newlines
+   and quotes from runs.jsonl content) are passed through argv `-m`
+   without any escaping required.
+4. **Chokepoint for every external effect.** `src/sync/runner.mjs` is the
+   only module that spawns processes or reads wall-clock time. Tests
+   replace it with a scripted fake. `registry-scope.mjs` is pure (file
+   reads + string logic only, no spawning) and independently testable.
+5. **Lock-on-write.** The PID lock ensures two sync runs on the same
+   host never both reach the `git commit` step. The lock is stale-safe
+   (10 minutes) so a crashed runner does not wedge subsequent ticks.
+6. **No stranded commits.** If push fails even after one rebase-retry,
+   exit 2 (`fail-push`). The next 30m tick will retry from the start —
+   discovering the local-only commit, pulling origin's new state,
+   rebasing on top, pushing again. Monitor on `fail-push` runs lasting
+   > 2 ticks.
+7. **Degrade gracefully, never crash on registry state.** A missing,
+   malformed, or device-unresolvable registry falls back to the
+   pre-rewrite unscoped behaviour with a loud warning — never a thrown
+   error, never a silently-scoped-wrong commit.
+
+## Project layout
+
+```
+packages/cli/
+  bin/
+    estate-sync       Node shebang shim (canonical bin name). One line.
+    sync              Same shim — back-compat alias, same entry point.
+  src/sync/
+    cli.mjs            Arg parsing (node:util.parseArgs), verb routing,
+                        exit-code translation.
+    run.mjs            Orchestrator: lock -> examine -> compute scope ->
+                        stage -> commit -> pull --rebase -> push. One
+                        function per step. (Commit precedes the rebase
+                        because git pull --rebase refuses to run with
+                        uncommitted changes.)
+    registry-scope.mjs Registry-scoped commit-scope computation. Pure —
+                        no spawning. Device resolution, mount-exclusion
+                        derivation, porcelain-output filtering, scope
+                        rendering for the commit body.
+    git.mjs            Thin wrappers around the git commands sync invokes.
+                        No spawning of its own — delegates to the runner.
+    runner.mjs         Chokepoint. The only module that spawns processes
+                        and reads the clock.
+    lock.mjs           PID-file lock with stale-after-10m semantics.
+                        Pure functions over an injectable fs.
+    runs-digest.mjs    Discovers cron tool runs.jsonl files and tails the
+                        last N records to compose a commit-body summary.
+  test/sync/
+    *.test.mjs         node:test.
+```
+
+Runtime-only (gitignored), under `<repoRoot>/.cache/estate-sync/`:
+`.lock` (per-host PID file), `logs/runs.jsonl` (per-host audit roll-up),
+`logs/<ts>.log` (per-run diagnostic logs, if added later).
+
+## Tests
+
+```
+node --test packages/cli/test/sync/*.test.mjs
+```
+
+Tests use dependency injection over mocking libraries. Real git, real
+filesystem mutations (outside of `tmpdir()`) and real network never
+appear in the suite.
+
+Coverage:
+
+- `lock.test.mjs` — acquire on empty path, contention with a live PID,
+  steal on a stale PID, steal on age-exceeded, release-only-if-still-ours.
+- `runs-digest.test.mjs` — discovery (known parents, missing dirs
+  tolerated, sync's own log excluded), tail (last N, malformed JSON
+  lines skipped, empty file → empty array), body composition (header,
+  per-tool sections, footer, edge cases).
+- `git.test.mjs` — argv shape of every git wrapper call.
+- `registry-scope.test.mjs` — device resolution (exact host, device-id
+  match, short-name match, unresolvable), entitlement resolution (known
+  device, unknown device, repo missing from repos.json), exclude-dir
+  derivation (mount `to` union, `.vault/` always present, dedup + sort),
+  porcelain-path parsing (plain entries, renames contribute both sides,
+  short/malformed lines skipped), in-scope filtering (mount-owned dirty
+  file excluded, foreign-agent run-state excluded, `.vault` change
+  excluded, estate-native change included, untracked file inside an
+  excluded subtree never staged), no-registry / malformed-registry /
+  unknown-device fallback (all degrade to `registryPresent: false` with
+  a warning, never throw), scope-section rendering (scoped and unscoped
+  shapes).
+- `run.test.mjs` — noop-nothing-to-do, noop-locked, dry-run no side
+  effects (asserts fetch->add->commit->pull->push ordering in the plan
+  output), dry-run on clean-but-behind tree omits add/commit, dirty
+  happy path (asserts fetch precedes add, add precedes commit, commit
+  precedes pull --rebase), regression coverage for the dirty + 0 ahead +
+  0 behind case and the clean + remote-has-new-commits case, rebase
+  conflict path (fail-rebase + audit + rebase --abort invoked), push
+  retry succeeds, push retry fails (fail-push), fetch failure during
+  pull tolerated, fetch failure during push-retry surfaces as fail-push,
+  auto-resolve on allowlisted regenerated artifacts, still fail-rebase
+  on any non-allowlisted conflict, mixed conflict fails without partial
+  resolution, `.sync-config.json` override extends the allowlist,
+  rebase --continue failure after resolution still fail-rebases,
+  **registry-scoped staging** (mount-owned dirty file not committed,
+  foreign-agent run-state not committed, `.vault` change not committed,
+  estate-native change is committed, no-registry fallback warns +
+  commits all, untracked file inside excluded subtree not staged, all
+  dirty paths excluded → no commit attempted), commit title/body reflect
+  `estate-sync` naming and the scope-decision section.
+- `regenerated-artifacts.test.mjs` — defaults pin the known distill
+  outputs, glob semantics (exact / `*` single-segment / `**` deep),
+  classifyConflicts partitioning, config loader edge cases (missing
+  file / malformed JSON / non-array field / non-string entries).
+- `cli.test.mjs` — `--help`, `-h`, no-args, unknown verb, unknown flag,
+  for both `estate-sync` and `sync` bins (identical behaviour).
+
+## The tooling standard
+
+This tool follows [`packages/core/docs/standards/tooling.md`](../../core/docs/standards/tooling.md)
+(§1 identity, §2 Node-only, §3 zero deps, §4 structure, §5 CLI,
+§6 exit codes, §7 chokepoint, §8 testing, §11 camelCase JSON,
+§15 audit-record, §16 gitignored operational artefacts).
+
+## Relationship to other tools
+
+- **distill** writes the staging→knowledge promotion outputs. It does
+  not commit or push — sync picks those up on its next tick (if the
+  paths it wrote to are in-scope; distill's own outputs under
+  `operator/knowledge/` are canonical-owned mount content on most
+  estates and land via the library pipeline, not this tool).
+- **library-sync** (`operator/extensions/tools/library-sync/`) owns
+  ALL mount-owned content, including `agents/*` run-state — this is
+  exactly the set estate-sync now excludes by construction.
+- **wsd-ingest** writes per-entry markdown into `agents/dave/staging/`.
+  Under the current registry, `agents/dave/` is a mount `to` path (the
+  `stravica-library-hq` repo's `agents/barry/dave/` mount) and is
+  therefore excluded from estate-sync's commit scope — that content
+  reaches canonical exclusively via the library up-path, never via this
+  tool's git commit.
+
+Cross-host visibility latency: estate-native outputs written by a cron
+tool reach origin at the next sync tick (max 30 minutes behind
+real-time). Mount-owned content's visibility latency is governed by the
+library pipeline's own cadence instead.