agentleFS
ashfulcraashfulcra/fulcra-tools/AGENTS.md

fulcra-tools

AGENTS.md10 starsChanged 2 months agoMITView on GitHub

Your entry point to this repo. Fulcra helps agents know their user, know what's happening in their user's world, work with their user's other agents, and become more helpful over time — the packages here are working examples of all four. This file covers the non-obvious environment and the conventions you can't infer from the source; the README.md tells the top-level story (what each package is, how to install the pieces) and this file does not repeat it. Keep the…

  • Reads credentials

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

19 rules. About 0 are common, 6 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    README updates are required with every change: Every update to Fulcra Tools or anything in it must update the relevant READMEs in the same …

    line 60
  2. Distinctive:

    This file is a ship-gate artifact: Every PR that changes agent-facing behavior — CLI verbs, skills, conventions, environment requirements, …

    line 68
  3. Distinctive:

    Keep status, health, worker and explicit-access error classification consistent: pending/changed reads require a quiet recheck, not another …

    line 145
  4. Very specific:

    Selected local-source uploads: use Collect's captured Fulcra token, never the CLI's independently stored account.

    line 170
  5. Very specific:

    All packages, plugins, skills, examples, and release artifacts must be reusable without personal accounts or machine-specific values.

    line 211
  6. Distinctive:

    Never put synthesized knowledge into two-way sync working files or infer a source grant from a map/manifest.

    line 286
  7. Very specific:

    Reconcile interrupted notarization before submitting again: Verify the configured profile with notarytool history before a release build.

    line 372
  8. Very specific:

    Do NOT use --all-extras here: it pulls the macos extra, whose PyObjC wheels build by shelling out to /usr/bin/sw_vers, which does not exist …

    line 504
  9. Very specific:

    Run tests: uv run pytest packages/ -q (must NOT hit external services).

    line 512
  10. Very specific:

    No team-particular identity in engine logic.

    line 563
  11. Very specific:

    When the trusted feed fold still corroborates tasks omitted by a full-scan listing, reconcile fails closed and preserves the current …

    line 577
  12. Distinctive:

    Do the reader sweep in the same change, and say in the PR which readers you checked — "I did not audit the others" is a finding, not a …

    line 584
  13. Very specific:

    Every rep at -8d, -9d, -10d, -12d and -15d returned HTTP 500 with an empty body.

    line 601
  14. Very specific:

    When a role's registered maintainer: is also one of its own lease holders, the alarm cannot reach a supervising identity.

    line 681
  15. Very specific:

    Read health before anything else: UNKNOWN means the authority itself was untrusted and the rows must not be acted on.

    line 918
  16. Very specific:

    Prefer if cmd; then …; else ….

    line 968
  17. Distinctive:

    When reporting a BATCH, count the artifacts on the store rather than tallying exit codes you did not check.

    line 969
  18. Very specific:

    Legacy Bus-v3 migration is authority/cursor-only: Run coord-engine bus-v3 migrate <team> --dry-run first, then --apply only after every …

    line 985
  19. Very specific:

    Slug dedup + delivery rc: Every directive slug carries a payload hash (<title-slug>-<sha256(payload)[:8]>), so identical resends dedupe by …

    line 1109

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Fulcra Tools — agent guide

Your entry point to this repo. Fulcra helps agents know their user, know what's happening in their user's world, work with their user's other agents, and become more helpful over time — the packages here are working examples of all four. This file covers the non-obvious environment and the conventions you can't infer from the source; the README.md tells the top-level story (what each package is, how to install the pieces) and this file does not repeat it.

Keep the monorepo framing. These are unofficial, unsupported tools and skills vibe-coded by Fulcra's lawyer to work with Fulcra. Coordination and continuity work independently of Collect. Collect is an optional host for local/source connectors, not a prerequisite for using Fulcra. The root README indexes every package and bundled skill; retain the human introduction and verify release claims.

Coord v5 Codex automatic enrollment: reconcile one shared listener per environment/harness and its exact source/job-to-worker route. Follow the shared listener acceptance checklist. Interactive membership does not finish automatic setup. Keep a linked owned acceptance task or exact blocker until actual invocation, idle worker delivery and independent receiver evidence are verified; never silently substitute a per-worker heartbeat. Preserve monitoring and temporary fallback obligations until a verified replacement exists. This instruction grants no setup authority.

Record each new actionable user request as an owned bus task, or update the matching task. Keep its scope, status, prerequisites, next action, and completion evidence current. A continuity checkpoint is not a substitute for the task backlog.

Coord v5 managed listener enrollment checks current transport tool names/schemas and existing account-to-principal/source binding. Stale tool identity is unavailable, not proof of missing credentials or an empty bus. Preserve cursors, deduplication, pending delivery intents and existing routes; authorized shared enrollment is additive within the exact listener scope. A verified alternate transport does not prove hosted connector recovery or scheduled receiver execution. See packages/coord-v5/README.md. The packaged harness guide now gives centralized-listener recipes across desktop, CLI, cloud, browser, Gateway and custom-host environments. Keep recommendations, shipped adapters and verified native capabilities distinct; unavailable dispatch falls back to durable addressed attention, not per-worker polling or guessed APIs.

Coord V5 has an opt-in parallel transport read-updates route. Use shadow mode before gated deployment; update watermarks are not record cursors or complete-history proof. Quiet hints never cancel retained delivery obligations. Preserve the direct route, private journals and per-source scope; see the package README for audit/fallback limits.

Mesh request attention is distinct from transport cursors. The optional coord-mesh queue --attention-db ABS durably retains addressed directive/query/message/request requests before cursor advancement, including previously read rows in the returned window. Receiver receipt does not dispose of work; a reply requires a committed claim and exact independently verified response readback. Claimed/ambiguous replies never retry automatically. This adds no grants, native listener or authority to execute peer text. New mesh envelopes carry stable per-send mid identities; attention entries expose reply_to for original IDs and source-qualified historical mid-less records without changing source envelopes. Schema-v2 legacy ACK reconciliation records receipt only when in_reply_to is absent; upgrading v1 reopens matching ACK dispositions while preserving the source evidence and uncertain claims. Read the coord-mesh README before upgrading host consumers; stop old writers first, because the version fence applies on open.

README updates are required with every change. Every update to Fulcra Tools or anything in it must update the relevant READMEs in the same PR, including fixes, plugins, installers, commands, and workflows. If a package has no README, update its nearest owning README or add one. Update the root README when the change affects installation, available tools, or release status. Document current behavior and limits; label unfinished work. Reviewers must block a change whose README update is missing or stale. This is a standing repository rule.

This file is a ship-gate artifact. Every PR that changes agent-facing behavior — CLI verbs, skills, conventions, environment requirements, review rules — MUST update this file in the same PR. Reviewers: treat a stale AGENTS.md as a blocking finding. If your change doesn't alter what an agent needs to know, say so in the PR body ("AGENTS.md: no change needed").

No one-off fixes on coordination or continuity surfaces (operator law, 2026-08-14; earned by twelve strict-consumer incidents, OUTPUT-CONTRACT.md). Root-cause every incident and fix it upstream at the surface that produced it, not with a defensive patch at the consumer. The models reading these surfaces are smart; what they need from us is surfaces that are durable.

Apple Notes reconciliation/writeback: listing timestamps are not a content baseline. Reconciliation reads tracked vault bodies so edits near a sync are not missed; retain the complete internal change list and cap only report presentation. Partial AppleScript write failures must produce a failed report and failed run. Shared Collect Files text reads must validate a supplied exact-version size as a strict nonnegative integer and compare complete downloaded bytes before UTF-8 decoding, on both direct and signed-storage legs. A short 200/Content-Length prefix must not authorize Notes merge/write/checkpoint; absent metadata is not an independent size proof.

Selected-list task sync: Reminders uses EventKit, with separate read-only permission checks and explicit permission requests. No lists are selected by default. Import and source completion must re-check live selection, enabled state, and preview mode before each write. Task status is open or resolved; identity and generation fields bind a completion to the source task. Normalize task paths to absolute Fulcra paths at the Files adapter boundary for both history lookup and upload; the API rejects relative upload paths. Read all unseen Fulcra file versions so a concurrent bot edit survives an importer write. Task read_version requires metadata from the latest complete history snapshot; invalidate it before every listing attempt. Retain each exact version's supplied strict nonnegative byte size and compare direct/signed HTTP200 body bytes before decoding or task parse/render/checkpoint. Archive reads remain by ID; never borrow the current path or another version's size. Size-less older metadata supplies no independent length proof. Missing source tasks are never completion evidence. Todoist task-detail lookup can return checked: true after completion; accept it only with valid explicit completion evidence. Keep active-list validation separate: a checked task there still invalidates the snapshot. Recurring writeback is unsupported until the provider can atomically protect the intended occurrence. Capture RunContext.config_epoch with settings and pass it into the task engine; check it in the live selection callback. Configuration and credential transitions must invalidate pending journals even when no sync runs between the changes. Save configuration under a cross-process lock and publish it atomically. Merge each caller's edits against its immutable load/save baseline: enabled membership, interval keys, and individual plugin-setting keys merge independently. An unchanged stale value must never undo a disable or remove another caller's setting. Divergent edits to the same field raise ConfigConflictError before publication; reload and retry instead of force-saving the stale object. For explicit user submissions use enable, disable, set_interval, and update_plugin_settings(plugin_id, values): these preserve intent even when the submitted value equals the loaded baseline. Direct mapping edits carry only semantic differences and cannot represent an explicit unchanged-value request. Interactive Fulcra sign-in/sign-out must persist an account_transition gate and rotate all plugin epochs before changing the token, then rotate again before clearing the gate on success. Task callbacks reject the gate as well as stale epochs. Failure leaves the gate closed until an interactive retry succeeds; normal configuration saves and automatic token refresh must never clear it.

Automatic Collect token renewal must publish only the closed shared keys bearer-token and oauth-credentials through set_user_secret_quiet, never ordinary set_user_secret/keyring.set_password. The disposable mutation child suppresses legacy interaction and per-query UI, uses bounded private-pipe I/O, and requires an exact acknowledgement. Keep final account/revision checks and the consumed-grant no-replay journal; denial/timeout/ambiguous publication requires reconnecting. Explicit interactive sign-in remains separate. Tests must inject an isolated quiet backend or fence the native child, and must not interpret a synthetic quiet-write pass as signed-app Keychain acceptance. Native credential-helper timeouts are pending/UNKNOWN, not proof of a missing grant. Keep the outer credential wait longer than the child I/O and cleanup bounds. Do not signal a completed/reaped helper's old process group, and do not let cleanup permission errors replace the original read/write failure. Declare every field a source consumes in its availability/recovery inventory, including Trakt's optional created_at and expires_in OAuth metadata. Optional confirmed absence is different from denied or UNKNOWN access. Do not request another unrelated grant when the source consumes an omitted field. Keep status, health, worker and explicit-access error classification consistent: pending/changed reads require a quiet recheck, not another approval. Configure's recovery surface must include declared OAuth-managed fields outside input steps.

Strict Trakt scans pin one UTC end_at in the shared scan bounds, including 401 restart, while retaining exact pagination/count/ID validation. Do not accept inconsistent provider totals or treat a fixed date range as a transactional snapshot; backdated changes still fail closed before delivery/cursor progress. An explicit Trakt start_at setting narrows the live scan and participates in the captured settings/epoch/cursor scope. Keep earlier history as a separate owed reconciliation; do not infer its completion from a ranged run or alter a pending batch's original settings to make it fit the new range.

Trakt's development backend uses one versioned credential-bundle-v1 Keychain item for the complete token tuple. Logical field authorization must target that item, never start a per-field native approval batch. Ordinary snapshots are read-only; explicit edits and owned refreshes publish one whole bundle with exact readback. Keep legacy items, no-replay journals, epochs and provider identity pins. Unknown legacy timing metadata stays explicitly unknown, not guessed from item creation dates. Explicit PKCE reconnect may create fresh setup only after revoking the predecessor source; unreadable or corrupt current bundles never fall back to legacy secrets. Installed signed-upgrade acceptance is separate from source tests.

Public repository privacy

Selected local-source uploads: use Collect's captured Fulcra token, never the CLI's independently stored account. Use RunContext.collect_token() for selected-source uploads; its missing/expired token requires reconnecting in Collect. fulcra_token() is a compatibility alias with the same Collect-only behavior; see the canonical strict authentication contract. Capture and compare the stored token as well as the epoch before uploading. Use the bounded credentials.get_user_secret_fresh() read for capture and final upload guards; the ordinary cached reader cannot detect another process changing the token. Do not re-canonicalize a selected folder path on subsequent scans: substituted ancestor/root links must fail closed. Partition content-hash state by the authenticated destination account. Before each source read and upload, validate the captured plugin epoch, source/collection selection, preview mode, enabled state and account-transition gate. Hold the shared configuration/account lease through the final consent check and upload. Use descriptor-anchored no-follow regular-file reads and a private snapshot whose identity, size and hash match the scan; consumers upload or render that snapshot instead of reopening the source pathname. Preserve file/traversal byte limits and suppress private paths and credentials from complete error tracebacks.

Local-source setup health checks capture the current persisted plugin epoch, allow checks before enablement, and validate saved selection/settings plus the account-transition gate before scanning and before each bounded content read. Recheck after the scan; revoked consent must return a failed health result with no preview. Do not use the setup context's empty worker epoch or bypass these guards for local-only previews.

Selected Notion pages: the notion-pages plugin reads only explicitly selected page roots and ordinary nested blocks. Never add workspace search, child-page/database traversal, synced-block following or attachment downloads implicitly. Use omission markers for unsupported content. Keep credentials in Keychain, preview on by default, content hashes scoped to the destination account, and captured settings/epoch/credentials checked before reads and under the shared configuration/account lease before uploads. Use the strict Collect token and bounded fresh credential checks. Its source-tree registration is not a claim that the released installer includes it; live provider and signed-installer verification remain separate release prerequisites. Setup health probes must capture the current persisted epoch and guard each read too; allow probes before enablement but abort changed selection/credentials. Reject missing known block fields and inconsistent pagination instead of saving a partial page as an empty success.

All packages, plugins, skills, examples, and release artifacts must be reusable without personal accounts or machine-specific values. Follow docs/PRIVACY.md before publishing. Run the tracked-tree privacy guard and credential scan; also review fixture provenance, public messages, and generated artifacts. Account-specific UUIDs and device names remain private even in retired-channel fixtures. Adoption claims must use the authority-checked bus sender; a failed send must not fall back to a hard-coded channel or write its success marker. Passing a pattern scan is not proof that all personal information has been removed.

Credential scans use .gitleaks.toml with the default rules and version pinned in privacy CI. Exemptions require an exact public identifier AND an enumerated source path; never ignore a whole path, rule, fingerprint or line. Configured controls must still detect neighboring synthetic keys, wrong-path and prefix/suffix candidates, and other-rule fixtures; malformed configuration must fail rather than report a clean scan.

Answers bridge configuration: account IDs and project URLs stay private, just like credentials. Ship only synthetic examples; the privacy guard rejects the private account config and credential filenames even inside archives. Select the config with ANSWERS_LINEAR_CONFIG or --config, require COORD_TEAM, and load credentials only from LINEAR_API_KEY or an explicit ANSWERS_LINEAR_ENV. Help and local setup checks must not contact services. Preserve the existing sender, workstream, and promotion source when migrating an operator's private configuration so a pending promotion retry keeps its task identity.

Where to start

Zero state — never installed coord-engine, or joining from a fresh / remote / sandboxed host? Start at docs/coord/GET-ON-THE-BUS.md — install → auth → (remote egress) → team bootstrap from zero → join. The probe grid below assumes the engine is installed and a <team> exists; if coord-engine is command not found or you have no team yet, the grid can't help you — the quickstart is the entry.

Already on the bus? Run the probes top to bottom, then jump to the layer you're touching. First failing probe is where your setup gap is.

Probe / questionCommandPasses whenWhere to go
Engine + auth usable?coord-engine doctor <team>exits 0 — tooling present, store reachablenever installed / command not found / no team yet → docs/coord/GET-ON-THE-BUS.md (install → auth → bootstrap → join). Otherwise fix the reported gap (auth: fulcra auth login; missing/old coord-engine: reinstall)
On the bus?coord-engine queue <team> --agent <you> (bus v3; raw get-records if the engine predates v1.7.0), then coord-engine briefing <team> --agent <you> for the durable boardqueue read completes — and if it stages a queue-delivery token (cursor schema v2), the probe passes only after every record is classified and queue commit succeeds; briefing prints your identity, role inboxes, reviews owedCoordinate on the bus — events are the wake surface, the fold is the full picture
Two identities joined end to end?coord-engine acceptance pair <team> --agent <A> --peer <B>every timed hop prints HOP N PASS and the command ends PASS pair A<->B; any bad nonce, missing checkpoint, stale resume, degraded queue, or failed write exits at FAILED AT HOP N with raw evidenceGET-ON-THE-BUS.md
Own worktree?git worktree listyour cwd is a dedicated worktree, not a shared checkout (no conflict markers or foreign staged files)Working tree — carve your own before committing
Touching Collect / the daemon?——The daemon (Collect)
Touching coord conventions?——Coordinate on the bus
Touching the platform surface?——Fulcra platform surface & records
Touching CI / hooks?——CI and workspace membership

Layout

uv-workspace monorepo, macOS-first. Packages under packages/, agent skills under skills/, each package with its own README, build, and tests.

  • Map Our Team — skills/map-our-team provides a shared index of a team's knowledge sources, owners and connection instructions. Its skill covers the steward's map and each teammate's onboarding, checks and offboarding. It uses Fulcra Files and the external connect-our-agents skill; content and access controls stay at their sources. Read its README for installation and validation limits before using it with a real team. Create honors an existing build/save request without another approval, checks inherited map audiences even in an empty account, and separates storage-owner, human operator and verified agent-contact IDs. Lifecycle retries preserve unchanged files/timestamps, and Add verifies the grant before roster publication plus exact map readback. Honor a named writer across chats for the same operator. Gap recovery researches current evidence and useful roles before asking for consequential missing decisions; documenting a role is not appointing an owner. Optional producer manifests advertise connector-owned sources under /knowledge-sources/v1/; the skill works without them. Its maintenance recipe supplies the shared recurring run prompt; template guides link it instead of duplicating the protocol. It installs no scheduler or implicit write authority. Preserve the steward's map writer and producer's source/index writers. Never put synthesized knowledge into two-way sync working files or infer a source grant from a map/manifest. Check reader access and source freshness separately from producer publication; unknown provider namespaces stay unknown. Company-owned installations follow company-deployment.md: company map/connector storage stays separate from member-owned proposal streams and producer instances. Review access is not onward-publication authority; Notion credential kinds and Attio token levels do not replicate provider ACLs into Fulcra copies. Use the first-time setup guide for company/member prompts and the optional public maintainer feedback route. The maintenance recipe optionally polls incoming joins and member proposals; queue-only is the default, explicit exact-member delegation gates acceptance, and proposal mode stages all join effects. Do not install the retired coord listener for this flow. Claim listening only after a real scheduled run. Member check status needs a verified authorized audience too, including inherited root/group/account-wide shares. Unknown or unexpected readers require an already authorized private checkpoint or chat fallback; preserve unrelated grants.
  • Collect — the local ingest side: collect (the daemon: control socket + FastAPI onboarding wizard + worker subprocesses), menubar (the macOS menu-bar app, PyObjC / rumps), fulcra-common (shared API client + ingest pipeline), plus the importer packages (dayone, csv-importer, media-helpers, attention, netflix-skill, …). The published Apple-silicon beta is 0.1.5, signed/notarized/stapled from source 47fbe9a2d23d906a2f6b7c63710ca61199a69f2b; its public asset bytes match the qualified installer. Use the current download in docs/collect.md. This package acceptance does not complete browser v1 activation, source-host retirement, every interactive flow or complete legacy historical conversion.
  • fulcra-media webhook readiness is a synchronization contract. Its JSON {"stage":"ready"} lifecycle line is emitted only after the local /health endpoint has served a request, not merely after bind/listen. A parent may therefore send SIGINT/SIGTERM immediately after reading that line; the command must emit its shutdown line and exit cleanly. Do not move readiness ahead of the serve-loop health probe — BaseServer.shutdown() can deadlock if it races serve_forever() initialization.
  • packages/gmail (fulcra-gmail) — the local, read-only Gmail relay: multi-account, crash-safe (append-only ledger + contiguous-frontier watermark), landing selected emails in Fulcra Files and relaying matches over the coord bus. The OAuth client MUST be an External, Desktop app client: Internal excludes personal Gmail accounts, and a Web client's secret is confidential and unsuitable for a shipped local relay (Google treats a Desktop client's secret as non-confidential, which is what lets one shared client ship to many installs). The full OAuth clickpath, account caps, logging rules, ledger/relay/pipeline design, and the in-plugin rule builder live in packages/gmail/README.md — read it before touching the relay.
  • packages/purpleair (fulcra-purpleair) — a scheduled/live_polled Collect plugin polling PurpleAir air-quality sensors (cloud API or a sensor on the LAN). On this development branch it writes per-measure v1 Metric tracks with declared units, guarded pending samples and exact readback. AQI is derived locally using the existing formula; see its limits and rollout status in the PurpleAir guide.
  • Shipping the Safari app to TestFlight — packages/attention/safari/scripts/release_testflight.sh does the whole mechanical path (both JS bundles → archive → payload check → export → validate → upload) and refuses to start without three things a runner must never hold: an Apple Distribution certificate, an App Store Connect app record for com.fulcra.attention, and an ASC API key passed as ASC_KEY_ID / ASC_ISSUER_ID with the .p8 at ~/.appstoreconnect/private_keys/AuthKey_<KEYID>.p8. Developer ID Application is not a substitute — that signs the notarised .dmg for direct download, not an App Store build; they are different certificates for different channels and assuming otherwise fails late, looking like a provisioning problem. --dry-run stops after export; any other argument is rejected with exit 2 rather than falling through to an upload, because a consumed build number is not recoverable. CURRENT_PROJECT_VERSION must increase on every upload.
  • The Safari destination step is a requirement. The containing app must show which "Attention" definition this device writes into and let the user change it (DestinationView.swift). EnsureAttention's oldest-first auto-adopt is a DEFAULT, not intent — with two definitions it silently takes the older one and the data lands in the wrong place while validating fine. Do not remove the picker on the grounds that auto-resolution "already works".
  • Running the Safari Swift tests — xcodebuild -scheme FulcraAttentionTests -destination 'platform=macOS' test, but build both JS bundles first (npm ci && npm run build && npx vite build --config vite.safari.config.ts in packages/attention/chrome): the scheme builds the macOS app, which embeds the extension, which copies a built bundle as resources, so a clean checkout fails on missing files unrelated to the tests. Platform-agnostic logic belongs in the macOS app target even when only the extension uses it at runtime — that is what makes it reachable by @testable import FulcraAttention.
  • Sign the native command launchers explicitly. Briefcase does not discover the extra fulcra-collect, fulcra, and fulcra-api executables in Contents/MacOS. The release script signs each with Developer ID, a secure timestamp, and hardened runtime before Briefcase seals the outer app. A valid outer resource seal alone does not establish notarization eligibility.
  • Reconcile interrupted notarization before submitting again. Verify the configured profile with notarytool history before a release build. A submit command that ends without an ID does not prove that Apple received nothing. Preserve the artifact and private log, check history and native prompts, and reconcile the existing attempt first. Keep receipts, credentials, and machine diagnostics outside the public tree. Do not publish a signed candidate until notarization, stapling, and Gatekeeper acceptance are verified.
  • Shipping a new plugin in the frozen macOS app — the menubar Briefcase requires is the ONLY list you edit, but it is not sufficient on its own: a monorepo package isn't on PyPI, so the release build must also build a local wheel into wheelhouse/ and prove it landed (Briefcase can exit 0 with an empty app_packages). Both steps derive from packages/menubar/scripts/bundle_manifest.py, which resolves each workspace package's real import name from its own hatch config (the mapping is not mechanical). Do not reintroduce a hand-written package list in build_macos_app.sh; test_registry_manifest.py fails if you do (this drift shipped once — caught in PR #455 review).
  • Shipping a new plugin: document it in the same PR. docs/how-do-i-get-my-data.md states that it lists every source Collect can pull from, so an undocumented plugin makes that opening sentence false. The catalogue cites plugins by id in backticks, and packages/collect/tests/test_docs_coverage.py fails when a registered plugin appears nowhere in it — so the test tells you at PR time, not a user months later. A plugin that genuinely is not a user-facing source goes in that file's _NOT_USER_FACING map with a reason, which is a deliberate statement, not a way to quiet the test. The check is coverage only: it proves the source is mentioned, never that the prose is right (this drifted for real: two shipped plugins were undocumented and one section affirmatively denied a plugin that was registered — the coverage test now catches the first class; only reading the prose catches the second).
  • coord — the agent-coordination layer. In prose it is coord; the engine is packages/coord-engine (a stdlib-only CLI, coord-engine), and the skills under skills/ — the fulcra-agent-* family (e.g. fulcra-agent-review, fulcra-agent-continuity, fulcra-agent-automation) plus coordinator-discipline — are how an agent actually drives it. (The coord2 codename is fully retired — code, identifiers, and prose all say coord; installers migrate coord2-era on-host artifacts automatically when re-run.) The first-generation fulcra-coord and fulcra-coord-files packages were retired after their last live annotations surface moved to fulcra-common. Their provenance remains in git history; all coordination work uses coord.
  • packages/coord-tracker-bridge — the alpha, provider-neutral projection core for reflecting coord work into external trackers (normalized snapshots, versioned policy, a pure diff plan, a Linear adapter). Workflow order, lane policy, and adapter contracts: packages/coord-tracker-bridge/README.md.
  • packages/aicq-claude-mod — alpha Claude Code mod (function-hook plugin, not a Python package; excluded from the uv workspace): AICQ in a Claude Code session. It polls connect-our-agents/1, legacy mesh and fulcra.workspaces/1 on a timer through the fulcra CLI, groups messages into collaborations with work states, draws /aicq (SVG on desktop), and responds per the four AICQ modes (heartbeats and acks never wake; 4 auto-turns/hour/collaboration cap). Sends read back before claiming delivery. /aicq waiting ranks human approvals, replies and blocked-on-owner tasks; blocked tasks and local pending drafts remain visible despite age. ignoreAfterDays defaults to 5 (0 disables ignoring), and aicq_inbox accepts include_stale. The owner principal defaults to user; preserve explicitly configured principals and placement. Session links come only from owner pins, exact app/V5 session matches, or own-account agent-links/1 reports, through the shared allowlist. Alias folding must preserve owner overrides and thread lookup. Interpret coord read-degraded markers even at rc 0; report failures and the 80-report read cap as partial coverage. The pane supports terminal and desktop; mobile is not implemented. Gate: claude plugin validate + claude plugin test on a mods-capable build. Install anywhere from the repo's plugin marketplace (.claude-plugin/marketplace.json): /plugin marketplace add ashfulcra/fulcra-tools, then /plugin install aicq@fulcra-tools. Details: packages/aicq-claude-mod/README.md. Filtering presentation never completes work. Second-instance session routing remains an installation acceptance check.
  • Coord retention is on by default: terminal and quiet proposed tasks archive after 14 days, settled review families after 7 days, and dead presence shards are pruned after 7 days. COORD_RETENTION_DAYS=0 or reconcile --retention-days 0 is the explicit kill switch; invalid values fail safe to the enabled default. Hot review folds consult a compact settled index instead of repeatedly classifying historical tombstones, and the legacy artifact/ namespace is consolidated into artifacts/. UNKNOWN listings stay hot, moves are copy-verified rather than destructive-only, and archived work reverses through task restore or review restore. An archived task is owed by nobody: retention writes one bus-v4 close to all for it after the source delete succeeds (never before — closing hot work hides it); an unreadable bus-v4 config or failed write is a v4 close FAILED warning, not a rollback, and never "no plane". The close is durable: retention writes a marker under _coord/retention/pending-v4-close/ BEFORE it moves any ack/response shard or deletes the source (a task whose marker cannot be written stays hot with every shard in place) and clears it once the close has an answer, and EVERY pass (not only the daily archive pass) retries what is still queued, at most 50 per pass with the rest reported as cap reached. A failed close or a pass killed mid-way is therefore retried, never lost. A retry never closes a task whose doc is hot again: its close may already have landed, so it re-opens from that doc and keeps the marker until the open succeeds, and it keeps the marker while that path is UNKNOWN. A close that races a restore re-reads the hot path afterwards and re-opens from the doc it finds; if that re-open fails or the read is UNKNOWN, it re-writes the marker (the restore may have just cleared it) and the next pass finishes the job. task restore clears the slug's marker only after its move succeeds, then writes the matching v4 open and exits 3 if it cannot. Archives from before this rule left phantom opens in the folds; those need a separate verified cleanup. Note the age thresholds above are necessary, not sufficient: tasks and reviews share ONE per-pass archive cap and tasks are swept first, so a large task backlog defers review archiving indefinitely. When that happens the pass now warns retention: cap reached ... N review slug(s) not examined this pass — treat that warning as "review retention is not running", not as routine throttling.
  • The OLD one-shot migrate exporter and the unused atomic handoff convenience verb are retired (bus-v3 migrate, described under Coordinate on the bus, is live and unrelated). Reassign live work with task update --assignee <agent> --next "..."; when another session needs resumable context, write the continuity snapshot first and then reassign the task.
  • Machine JSON is compact by contract: public non-ATC --json documents, the single-array threads result, and _coord/summaries.json omit insignificant whitespace while preserving parsed values and degradation markers. Tests and consumers compare parsed JSON unless byte layout is the explicit contract.
  • Other agent-facing layers (Continuity, Prefs, Vault, FDE, ATC) are described in the README; their skills and READMEs carry the detail.

Setup & tests

  • One command: bash scripts/setup.sh — installs the right Python + uv extras + the fulcra CLI, then runs the suite to verify (macOS-first; the menubar's PyObjC deps are macOS-only).
  • The manual equivalent is OS-dependent, and the difference is silent — which is the whole reason this bullet is two paragraphs.
    • macOS: uv sync --all-packages --all-extras. Bare uv sync is NOT enough — pytest lives in each package's dev extra and PyObjC/rumps in the macos extra, so a bare sync fails tests with Failed to spawn: pytest and the menu-bar can't import. Any sync must keep --all-extras or it prunes pytest + PyObjC back out.
    • Linux: uv sync --all-packages, then select the dev extra at RUN time: uv run --all-packages --extra dev python -m pytest packages/ -q. The Linux CI job (uv-workspace.yml) uses the same extra selection over an explicit list of package test paths. Do NOT use --all-extras here: it pulls the macos extra, whose PyObjC wheels build by shelling out to /usr/bin/sw_vers, which does not exist on Linux. The build dies with FileNotFoundError and nothing is installed. That failure does not look like a failure afterwards: it leaves a .venv containing python and nothing else, so ls .venv succeeds, the venv "exists", and the next thing to run is a test that cannot import anything. Measured here on 2026-09-05 — the macOS line above was followed on a Linux container and produced exactly that.
  • Run tests: uv run pytest packages/ -q (must NOT hit external services). For targeted package/test runs, use uv run pytest -c pyproject.toml <paths> -q: package-local configs otherwise exclude root fixtures. Root fixtures supply a dummy token, disable native Collect Keychain selection and install the test-only Python network guard. Ordinary external DNS/TCP/UDP calls fail before I/O with a static error; numeric loopback, exact localhost, Unix IPC and MockTransport remain available for fixtures. This is a function-scoped Python patch, not an OS or subprocess/native sandbox: collection-time/earlier-fixture I/O, imported aliases and already connected descriptors are outside its scope. Tests replacing guarded calls must install hermetic substitutes. Never run a regression's RED against real credentials or an unmocked external client. Trace the PRE-migration auth path as well as its replacement before actual-caller RED: a legacy token subprocess can escape the parent Python network guard and uv --offline. Fence subprocess/OS shell, network and saved-auth fallbacks before loading the caller, with function-scoped synthetic fixtures restored after each test; never infer historical absence of child credential effects from a blocked parent request. Native integration probes run separately with explicit isolated fixtures. Root fixtures also isolate the OS-user Trakt owner journal and refuse quiet Trakt writes or explicit Trakt authorization unless the test supplies a synthetic backend. They do not make generic keyring getters/setters safe. Keep private profile/config paths and early child/auth/network tripwires in actual-caller tests, including imported path aliases before any directory/lease mutation. Process tests that may run after threads start must use fresh spawn children, rather than inheriting a threaded parent with fork. Re-establish private paths and auth/native/network guards in the child before application imports; parent monkeypatches are not inherited. The Trakt process helper demonstrates this test-only containment, which is not an OS sandbox. See the guard tests.
  • Editable install: the .venv imports the live workspace source, so a code change is picked up by restarting the daemon, not re-syncing.
  • A pass/fail count is a property of (sha, interpreter, cwd) — never of the sha alone. Measuring the engine at one merge commit gave 66 failed, then 1 failed, then 0 failed, from three cwds over the same source. From the repo root, the .venv's editable install resolved coord_engine to a DIFFERENT checkout — the 66 failures belonged to a stale working tree, not to the sha under test. From the package directory, coord_engine/ sat on sys.path, and the subprocess in test_obligations_engine_absent.py — whose whole job is to assert the engine is NOT importable in its sandbox — inherited that cwd and found it. Only an isolated venv holding a non-editable install, run from a repo root, measured the build actually under test. So print module.__file__ for the package before you report a number, and say which cwd produced it: a count without that pair is not evidence, and two of those three numbers would have been a false report to the operator. The rule generalizes past Python — whenever a tool resolves an implementation by search path, the search path is part of the measurement.
  • Pull latest into a checkout with bash scripts/update.sh (git pull + uv sync --all-packages --all-extras + restart daemon/menubar).
  • PyObjC-free logic is split into its own modules so tests run on Linux CI; macOS view-layer tests are marked and skipped off-darwin. Keep new PyObjC imports lazy (inside functions), never at module import time.
  • No team-particular identity in engine logic. review restore gated a whole code path on files != ["<one-agent>.md"], so the verb worked for exactly one agent on exactly one team and told everyone else "unexpected archived verdict shape". Predicates belong on the SHAPE (how many shards, is there a doc), never on whose name is in the filename — the repo generalizes, and the team's particulars live on the team's store.
  • continuity snapshot exits 3 and says so when the write did not persist. transport.write returns False on a transport failure rather than raising; the snapshot path once swallowed that and still printed snapshot <id> at rc 0 — found live during a store outage, leaving a successor to resume from the PREVIOUS checkpoint believing it current, exactly when parking matters most. Any caller of transport.write must treat False as failure; it is not a Falsy-but-fine return.
  • A task-directory listing that returns rc 0 is not automatically complete. When the trusted feed fold still corroborates tasks omitted by a full-scan listing, reconcile fails closed and preserves the current generation, summaries, and index. This catches the live intermittent-empty listing shape; do not turn that disagreement back into authoritative task deletions.
  • Audit every existing READER before you change what a marker MEANS. A marker's meaning is fixed by everything that acts on it, not by the writer's intent, so a new state or a new field is a change to every consumer at once. Do the reader sweep in the same change, and say in the PR which readers you checked — "I did not audit the others" is a finding, not a footnote.
  • health's continuity audit reads ONE pointer per agent (continuity/LATEST.json, written only AFTER the snapshot itself persists), not every snapshot — a store listing carries no mtime, so the walk is one read per task and, measured at fleet scale, hundreds of serial reads that repeatedly timed health out. A missing pointer is UNKNOWN, never stale — only "has never checkpointed" (proven by one extra listing) is a finding; continuity_unknown reports the rest. A failed pointer update REMOVES the old pointer — with no conditional write, deleting the cache is the only way to stop a stale timestamp being believed; if it can be neither updated nor removed, the verb exits 3. Pointer updates are monotonic: an older snapshot must never move an agent's reported age backwards.
  • data-updates intermittently answers 200 with an EMPTY file_changes on a window that otherwise works. MEASURED, at the raw HTTP boundary (GET /data/v1/updates?start_time=&end_time=) and through the CLI, 2026-10-02:
    • -1d returned 13135 file changes (4.0 MB); -7d returned 106187 (32.7 MB).
    • Every rep at -8d, -9d, -10d, -12d and -15d returned HTTP 500 with an empty body; -20d/-25d returned 500 in most reps.
    • At widths that otherwise answer, some reps returned rc 0 with file_changes: [] and a populated data_types map — seen at -1d, -7d and -25d. The strongest single observation is two consecutive calls on the IDENTICAL range returning 0 and 105768. What is NOT established, and must not be written as if it were: any causal mechanism, and any rate. These samples do not isolate window width from time of day, endpoint state, or anything else, and the -1d false empty is direct evidence that a comfortably-working width can fail — so "the endpoint degrades under window size, more often the wider the window" is an inference, not a measurement, and earlier revisions of this paragraph asserted it. Frequency is likewise unestablished: batches of 6 and of 20 came back entirely clean. Observation requiring further measurement: failure frequency looked higher at some wider requests. That is all it is. Consequences a detector over this feed can actually rely on:
    • An empty file_changes is never proof of quiet, at ANY window width. It is a well-formed answer indistinguishable from truth by shape. COORD_FEED_EMPTY_CORROBORATION (below) checks it against a recent sub-window, catching every case wider than the corroboration bound and not one narrower than it.
    • A populated data_types beside an empty file_changes is a CANDIDATE signal, not a rule — records-processed and file-changes are different legs and may legitimately diverge over a quiet range. Do not build a hard check on it without measuring that.
    • Do not raise COORD_TRANSPORT_TIMEOUT in response to this. Two earlier justifications for that advice were wrong and are withdrawn: a longer bound cannot turn a 500 into a 200 (our transport maps rc != 0 to None = UNKNOWN, correctly), and the width/frequency mechanism above is not established. The reason that survives needs neither: a longer bound lets requests complete that would otherwise be cut client-side, and since an empty answer is indistinguishable from a quiet range, more completed requests means more chances to record a false clear. The original error is worth keeping in view — a timeout-causes-200 mechanism read off one 30s-fails / 120s-returns- empty pair, which repeated sampling showed was the endpoint's intermittency.
  • health freshness is SHARD RECENCY; the advance fact is separate. EVERY reconcile exit writes a health shard, aborts included — _write_health_shard runs before the early return — so a host that has aborted every pass for hours still renders [ok … 0.02h ago]. Measured on team/fulcra 2026-10-02: the task index had not advanced in ~16h while health reported 4/7 host(s) fresh with four [ok] rows, the only trace an unlabelled 1 warn. The shard could not have answered either — build_shard recorded warnings as a COUNT and dropped degraded/reason entirely, so the distinction was unrecorded, not merely unrendered. Shards now carry advanced plus degraded_reason, the fold adds advancing/aborting/unknown_advance over FRESH hosts only, and the text says DID NOT ADVANCE: <reason> per host plus a headline. A shard with no advanced key is UNKNOWN, never True — a missing field is not evidence a pass succeeded, and during a rollout a pre-upgrade host must read as unknown rather than accused or excused. fresh/stale/healthy and the exit code keep their exact prior meaning (one production reader, cli.cmd_health, audited): whether an all-aborting fleet should flip healthy is an OPEN REVIEW QUESTION, not something the fold decides. Known imprecision, stated not hidden: an inventory-only generation refusal still writes summaries.json as the compatibility cache and its shard call site never sees that reason, so it reports advanced: True with its warnings — "advanced" means was not aborted and wrote the index, never published a clean generation. The same shard now carries engine_build, and health compares it with the PIN= line of the store's adopt-latest.sh: each host reads = pin, NOT the pin, or build UNKNOWN, with at_pin/off_pin/unknown_build rollups over fresh hosts. The version label cannot do this: __version__ changes only on a release, so hosts running different commits can report the same version. A missing build is UNKNOWN, never current; "not the pin" may be ahead or behind, so it is never rendered as "behind". The exit code is unchanged.
  • The .settled marker's MERGE EVIDENCE is never overwritten by the tally cache: a settleable tally once stamped state: APPROVED over state: MERGED + merge_sha — found in production, where the very review status run to CHECK a closure destroyed it. Both the delete AND the write need the guard (fixing one is the neighbour trap), and the write overwrites ONLY a positively identified CACHE or a positively ABSENT marker — an UNKNOWN one (unreadable, unrecognised state:, a FUTURE schema) is preserved and reported. A review-settled/v2 marker written by a newer build must survive an older build's refresh.
  • Date/clock tests: a module that fixes a top-level NOW for its data must also pin the clock — an autouse monkeypatch.setattr(cli, "_now", ...) to a PINNED_NOW at/just after NOW (template: tests/test_threads.py), deriving relative ages from PINNED_NOW, never asserting against the real clock. Otherwise the suite flips red once wall-clock passes NOW + window. Enforced by tests/test_clock_pin_convention.py.
  • escalate never addresses a role's vacancy notice to the party who lapsed. When a role's registered maintainer: is also one of its own lease holders, the alarm cannot reach a supervising identity. The notice is still written and counted; it is REPORTED (stderr + directive body) and never rerouted. Fix the role doc's maintainer: field instead. The undelivered count is recomputed on EVERY sweep, the daily marker is a SUPPRESSOR and is never written for a notice that reached nobody, a closed-loop role re-surfaces every sweep, escalate reports undelivered=N, and the verb exits 3.
  • escalate does not restate a vacancy that is already on the board. The vacancy title embeds the date, so the slug differs every day and the per-slug existence check on dst (a classified read_classified(dst) since PR 694; a bare read(dst) is None before it) can never match across days; the daily marker suppresses only WITHIN a day. A state-change guard (roles.vacancy_already_open) now skips minting while a row for that role is open, and prints ALREADY OPEN when it fires — a suppressor that says nothing is indistinguishable from a sweep that never ran. Three properties are load-bearing and must survive any edit:
    • Role matching is EXACT, never a prefix. A prefix test would let reviewer suppress reviewer-2; an identity transform used to suppress an alarm has to be injective or it hides what it was not asked to.
    • An unreadable listing does NOT suppress. UNKNOWN silencing an alarm is worse than a duplicate row, so the guard falls through to minting and says it skipped.
    • Closed-loop vacancies are EXEMPT — that is what the re-surfaces every sweep clause above is FOR. The notice reached nobody, so there the repeat IS the delivery, and suppressing it would silence the only retry. This is not a change to re-notify: directives.renotify is "a strict filter OVER inbox", a read-side fold that writes nothing and keeps surfacing ONE unacked directive. escalate was re-MINTING, which is a different mechanism that shared the name. Suppressing the re-mint costs no visibility, because the standing row is unacked and the fold surfaces it anyway. The skill prose (skills/fulcra-agent-roles/) carries the same condition, since a hand-written inbox drop would re-create the debt the engine guard removes.
  • The no-team-internals CI guard PROVES it can fail before it reports clean. scripts/no-team-internals.sh runs --self-test first: it stages a fixture carrying a public IP and a session ref, asserts the scan flags both, and only then scans the tree. Its first version used \b, which POSIX ERE does not support, so git grep -E matched nothing and the check went green on every PR while structurally unable to find its leak class. Never use \b in a git grep -E pattern. A guard's green is only evidence when its red is reachable.
  • Environment hermeticity: the suite's answer must not depend on who runs it. cli.INHERITED_ENV maps each ambient variable the suite must neutralise to a representative value (identity: FULCRA_COORD_AGENT, FULCRA_COORD_HUMAN; channel: COORD_RECORDS_TYPE) — ONE mapping, so the fixture that clears the keys and the wall that populates them cannot drift. The coord-engine conftest clears them for every test, and tests/test_env_hermeticity.py re-runs the affected files under both an empty and a populated environment and requires the same outcome (dozens of tests once failed iff an identity was exported — line one of every agent's wake prompt). A test that needs a specific identity or channel sets it in its own body. A variable belongs in INHERITED_ENV when the suite reading it makes the ANSWER depend on who ran it; a variable that legitimately changes behaviour a test is about goes in NOT_YET_WALLED with the measurement instead. Measure siblings rather than guessing.
  • Identity and canonical reads have one authority each. Resolve an agent identity only through coord_engine.classifier.resolve_identity: explicit argument → FULCRA_COORD_AGENT → the per-cwd persisted identities/<realpath-hash>.json state entry → sanitized host. In particular, never let a host-derived id replace an exported session id: two sessions on one host must remain separate actors. An unreadable persisted identity fails closed rather than falling through to host; an absent file is the only state that permits that fallback. Canonical directory reads go through canonical_read; a successful empty listing is EMPTY, a data-updates lifecycle deletion is TOMBSTONED, and unreadable or ambiguous evidence is UNKNOWN rather than absence. An unrecognised input shape (including a listed directory) is UNSUPPORTED, not a clean result.

Coordinate on the bus

Durable work — anything another session or agent must see — lives on the coord bus (Fulcra Files), driven through coord-engine and the fulcra-agent-* skills. Subagent-only work stays OFF the bus.

IF YOUR MESSAGE ASKS FOR NOTHING, SEND IT --fyi. tell mints a proposed row that only the RECIPIENT can close, so a report, an ack or an FYI becomes a permanent open obligation its assignee cannot discharge — there is nothing to do. A reply sent with --closes closes its parent AND mints a fresh open row back at the sender, so two agents who both behave perfectly still net one open row per exchange. --fyi delivers identically — same durable ptr doc, same companion event, same appearance in the recipient's queue — but the row is born closed and never enters the open pile. This is the sibling of the merge-closes-review ruling (PR #561) one plane over: closure belongs to the terminal event, not to a separate discipline step nobody performs, and a notification's terminal event is its delivery. Use a plain tell when you are genuinely asking for work; use --fyi for everything else.

First time on the bus, or joining from a remote/sandboxed session (Claude Code cloud, CI)? Follow docs/coord/GET-ON-THE-BUS.md — it covers the egress allowlist (fulcra.us.auth0.com, api.fulcradynamics.com), headless device-flow auth (and the fulcra auth login HTTPS_PROXY caveat), the human-free token-refresh grant, team bootstrap from zero, the join sequence, role-takeover continuity (continuity resume at claim time), and the ephemeral-host doctrine (survival invariant + heartbeat duty for long-lived remote sessions). The canonical invocation is the bare coord-engine binary after uv tool install — uvx/uv tool run cannot resolve it (not on PyPI).

  • Named identities: personas are a convention for human legibility only; bus routing always uses the functional id, and the roster lives on the team's store.
  • Wake router — ships in the engine; evaluate acceptance per deployment. Scheduled wakes + queue reads are the standing pattern (status notes: README.md and docs/coord/BUS-V3.md). The contract, should you deploy one, is wake-router-SPEC.md + wake-router-PLAN.md; deployment (provisioning adapter scripts, scheduling a poller on a host) is a separate, operator-gated step. Bound and prefetch queue-entry reads so a growing queue does not make the reader exceed its wake cadence. Two pieces of doctrine outlive any deployment:
    • AN ADAPTER'S SUCCESS PROVES THE ADAPTER RAN — never that the AGENT ran. Axis 1, what success proves: a DIRECT adapter re-enters the model session by its contract; an INDIRECT (queued/alignment) adapter only lands a nudge or aligns a schedule, and is a viable wake chain only when its independent consumer — session loop, Routine, heartbeat — exists AND is verified running; a NOTIFYING adapter shows a human a banner, never a wake. Axis 2, is there an implementation on the named executor: registration and implementation are separate, so a route can look configured, validate, enqueue forever, and never deliver. Classify each axis on its own evidence; never collapse them.
    • EVERY HARNESS MUST NAME THE THING THAT RE-ENTERS THE AGENT — the mechanism that runs the model, never a script beside it (an OS scheduler job runs shell, not the model; see docs/coord/HARNESS-MAP.md). And never retire a working wake without naming its replacement and proving the replacement RUNS THE AGENT: a standing session loop was once replaced over two weeks by a notifier that woke a human, a headless invoke that could not authenticate, and a peek that never consumed — none ran the agent, while every layer reported success.
  • bus-v3 tag-provision never writes a registry entry without agent. One such entry makes every reader reject _coord/bus-v3/tags.json, which untags the whole fleet's events. The verb exits 2 instead, leaves the registry unchanged, and prints the uuids it created for a --tag-id-* retry. Tag names are capped at 30 characters by the platform, so an identity over 24 characters needs a shorter, hand-created agent tag passed as --tag-id-agent; the verb checks names before creating anything.
  • Durable tooling stash. An agent's operational bundle survives ephemeral machines via coord-engine stash push/pull/list: push refreshes a manifest.json (per-file sha256 + exec bit) and runs a fail-closed secrets guard (secret-shaped names and credential-shaped content are refused with the tripped rule named — team/<team>/** is readable by every agent on the bus); pull restores and fails loud on checksum drift. Procedures: fulcra-agent-durable-state.
  • On wake, read your event queue first — bus v3. One bounded get-records query against the team's coordination annotation. The full read/write contract lives in docs/coord/BUS-V3.md; the agent-actionable core:

    • Dedupe by record id, keep v:1 payloads addressed to you or all, fetch documents by ptr, and fail closed on any error or truncation — an unreadable window is UNKNOWN, never empty.
    • Zero fresh events is not proof of zero durable work. A successful text-mode queue read with no event rows and no obligations fold prints a stderr notice pointing to coord-engine obligations <team> --agent <you>; run that verb for the terminal durable-work answer. The notice preserves the queue read's rc 0 because its event window was read successfully; an unreadable event window still fails closed as UNKNOWN at rc 3.
    • Terminal read states are DATA / CLEAR / ABSENT / UNKNOWN / INVALID, and rc is never inferred: read state + error_code from the single JSON envelope (under --json, success is exactly one queue-result object and every nonzero exit exactly one queue-error object — empty stdout never means anything). INVALID (malformed bytes; human-fixable) is never ABSENT (the engine refuses to auto-recreate over a corrupt document) and never UNKNOWN (*-read-failed means retry; a retry never fixes a corrupt file).
    • A deliberate queue --consume takeover of another agent's cursor writes a durable audit doc BEFORE reading and is refused if that write fails; plain reads and --peek write nothing.
    • The read is cheap enough to ride every wake you already have — do not run a polling loop or resident listener for it. Keep fulcra-api current whenever you touch coord tooling (same pass, standing rule).

    Prove the write path after any install/upgrade — and whenever a recipient says it did not hear you — with coord-engine doctor <team> --delivery --agent <you> (rc 0: written, ingested, and parsed; rc 2: write refused; rc 3: written but not proven fleet-readable before the deadline). Engine currency. "The pin" (the commit in the store's adopt-latest.sh — what to install) and current_engine_version in the bus authority (a SEMVER FLOOR — the minimum engine the fleet accepts, compared at-or-above) are different objects: adoption moves the first and cannot touch the second, so every pin move that ships behavioural change evaluates a floor raise in the same pass, and raising the floor is also what reaches a dark host. Every queue read checks the floor for free and prints queue: ENGINE STALE when the runtime is older. Adoption-script doctrine, each clause earned live: a failed adopt must never leave the host worse than it found it — never force-reinstall a capability that works, self-heal a half-removed install once, and still FAIL when the retry fails; a cached "adopted" marker records what you DID, not what is on disk, so a skip must be bound to the ARTIFACT's own identity (the installed build's direct_url.json vcs_info.commit_id, PR #598), never a capability every candidate shares, and every unreadable/malformed/absent answer is UNKNOWN and takes the expensive path; when a check reads several evidence sources, define their combined evidence — an UNKNOWN member poisons the whole set; shipped-shell decisions live in functions a test can drive (reading shell proves nothing); and pre-publish acceptance runs on both macOS and Linux, because you cannot know in advance which failures are OS-specific. coord-engine doctor <team> --self is the currency check on demand and is TRI-STATE: rc 0 current; rc 3 stale (run the store's adopt-latest, re-run); rc 2 unknown (floor unreadable/absent/malformed) — comparison impossible is not current, so never read rc 2 as green; repair only on nonzero. coord-engine briefing <team> --agent <you> remains the fold over durable state — identity, role inboxes, reviews owed — honor every degraded row it prints as UNKNOWN.

  • VERIFICATION FAILS DIFFERENTLY FROM CODE, AND IN TWO DISTINCT WAYS. Broken code usually fails visibly. A broken CHECK hands back an answer that looks fine, so the failure reads as a clean result rather than as an error — which is why "verify more carefully" is not the defence. In five logged instances every agent involved WAS being careful, and each committed the error inside work whose explicit subject was that error. The two modes need different defences and neither covers the other:
    1. A broken INSTRUMENT returns a WELL-FORMED answer. A probe reading the wrong path reports zero rather than erroring; a test harness that collides on its own fixture fails in a way that mimics the bug it hunts; a control that varies an input which short-circuits BEFORE the code under test proves only that the short-circuit works. Defence: check the SHAPE of the result — is this answer plausible at all? — and check it against an earlier, narrower measurement of the same thing. Too clean to believe, or disagreeing with a prior measurement, is the signal; discard the whole run rather than reporting part of it.
    2. A broken INFERENCE returns a PLAUSIBLE answer. The instrument is fine and the reading is fluent, reasonable, and wrong — "those must be false positives from matching ids against a human-organised document" is the shape. Plausibility cannot catch this, because being plausible is the answer's whole problem. The only defence is going to the SOURCE artifact and reading it. This is the half no heuristic covers, and the half that ships. The trigger is behavioural, not scheduled: the moment you find yourself explaining a result away — reconciling an inconvenient reading with what you expected, ruling a mismatch to be noise, or narrating why a source need not be opened — is the moment to run both defences. That impulse precedes the wrong conclusion in every logged instance, which is what makes it useful: it is available while the answer can still change. Everywhere else a wrong inference is additive and leaves the measurement standing; here it silently deletes the evidence that you were wrong. Corollary for any bug whose subject is a wrong reading: assume your own verification of it carries the same defect, and check the instrument before you trust what it told you.
  • needs-me --json is contract 2: one envelope object, health first. stdout is a SINGLE JSON value — {"contract": 2, "health": DATA|CLEAR|DEGRADED|UNKNOWN, "source", "degraded", "basis", "rows": […]}. Read health before anything else: UNKNOWN means the authority itself was untrusted and the rows must not be acted on; DEGRADED means rows are a FLOOR (partial coverage — never infer absence); CLEAR is the only health that licenses "nothing for me". rc is a pure function of health (UNKNOWN|DEGRADED → 3, in text mode too). An incomplete parse is UNKNOWN; never truncate an authority read with tail/head and never regex fields out of a cut buffer. Other verbs migrate one PR at a time — a bare array is the contract-1 shape, scan its marker rows as before (docs/coord/OUTPUT-CONTRACT.md).
  • Class A results flow through the shared v2 outcome spine. coord_engine.outcome.CommandOutcome is the internal authority for state, coverage, rows, provenance, and rc; legacy contract-2 envelopes are adapters over that value. A required surface that is not verified is UNKNOWN and therefore rc 3 even when some rows are usable. New Class A folds must build the typed outcome first, then render text or JSON from it; do not recompute health or rc in a serializer. Text coverage lines mark optional surfaces as non-gating, preserving the required:false distinction carried by JSON.
  • If your harness truncates output, read the verdict off stderr. needs-me and briefing print their row payload with degraded and source markers inside it, so a truncating reader can lose exactly the part that says whether the read is trustworthy. Both emit one compact envelope line to stderr — needs-me: N item(s), health=…, forge=…, source=…, degraded=N, rc=N — which survives stdout truncation (a courtesy duplicate; the stdout envelope is the authority). needs-me --envelope-only gives you that verdict with no records at all, same rc. Trust the envelope's health and rc over a payload you cannot see the end of; degraded>0 or rc=3 means UNKNOWN or a floor, never clear.
  • A STATUS YOU PRINT IS NOT A STATUS YOU READ. The same defect the clause above describes shows up in our shell habits, where it is cheaper to commit and harder to see: a script emits a success line without reading the status it claims to report. Three instances in one week, all caught only by looking at the NEXT command's output rather than at the success message itself — rc=$? after a command substitution containing a pipe, the same after a pipeline, and a git branch -d that REFUSED while the surrounding script echoed cleanup done (the branch was still there on the next line).

    Mechanical form: a script that prints an outcome must read the rc it is describing, and where it cannot, it says so rather than asserting. The tell is a success message whose text was decided before the command ran.

    The shell mechanics:

    • rc=$? after a pipeline captures the last stage only — false | true and false | cat both yield 0, so the failure is invisible. Same for out=$(cmd | filter).
    • Capture immediately (cmd; rc=$?) before any pipe or substitution, or set pipefail for that stretch.
    • Our login shell is zsh, where the per-stage array is lowercase pipestatus — bash's PIPESTATUS expands to the empty string here and silently tells you nothing, which is this very rule wearing its own costume.
    • Prefer if cmd; then …; else …; fi over cmd; echo done.
    • When reporting a BATCH, count the artifacts on the store rather than tallying exit codes you did not check.
  • Bus-v3 convergence is authority-gated, not a rollout convention. The shared _coord/bus-v3/records.json atomically declares protocol and cursor schema versions, minimum safe reader/writer engine versions, cursor generation/activation, and the CHANNEL every writer resolves — writers read data_type from it at write time and REFUSE rather than falling back to a name lookup (never resolve a channel by name: a superseded definition can still read as live, so a by-name resolve silently writes where nobody reads). queue warns on legacy or mixed writer evidence and refuses an unknown/old reader or writer before cursor mutation; cursor v2 is physically isolated from legacy cursors, and after activation legacy activity is a loud health signal, never authoritative coverage. Full authority and activation contract: docs/coord/BUS-V3.md.
  • Legacy Bus-v3 migration is authority/cursor-only. Run coord-engine bus-v3 migrate <team> --dry-run first, then --apply only after every cursor is readable-legacy or absent; malformed or unreadable state blocks, apply is idempotent and never rewrites legacy cursors, and task/role documents are not a migration target. JSON contract in BUS-V3.md: never branch on rc alone — read state + error_code, and treat writes.authority: "ISSUED-BUT-UNPROVEN" as a write whose read-back did not prove the resulting store state.
  • Cursor v2 is transactional: read → process → commit — commit the token when the last row is a queue-delivery. Under an activated schema-v2 authority, queue stages one pending batch and prints a queue-delivery token; it does not advance coverage. Process every surfaced event to a durable terminal classification, then run coord-engine queue commit <team> --agent <you> --token <token> --result <record-id>=<completed|blocked|superseded|ignored> (repeat --result for every staged event; an incomplete or extra set is refused). A crash or missing commit replays the identical token and batch; a stale token is rejected; a repeated successful commit is idempotent. The store transport exposes no conditional write, so schema v2 remains fail-closed until a transport provides a proven compare_and_swap (a write/read-back imitation is not CAS); keep the authority on schema v1 until doctor proves every active writer compatible and the CAS gate passes.
  • The Codex safety-net watch checks its literal inbox before briefing (PR 484): one direct inbox --json read, then the authoritative briefing read — briefing's inbox subsection is never a substitute for the direct read, and a degraded surface falls back to the documented direct listing before reporting quiet. Deliberate redundancy against a stale or unreadable summaries index.
  • Retired (2026-07-27, operator-ordered) and REMOVED (2026-08-03, PR #523): the listen watcher as the wake surface — don't hand-roll a replacement. Discovering work by walking the file tree degraded ~9 ticks in 10 at fleet scale and hid work; the v3 queue read (cursored, fail-closed) replaces it. Replies to tell/respond/review request arrive as v3 events on the record queue — read it on your next wake (the send verbs echo replies:/await verdicts: breadcrumbs; see fulcra-agent-automation §2). Invoking listen is an argparse error; any surviving listen-state.json shard is historical residue. Presence stays time-dirty rather than feed-cached: each briefing evaluates the roster against the current clock, so an unchanged session shard still becomes LAPSED when now >= until.
  • Review handshake. Nothing lands without an independent review by a different agent identity than the author — that review is the control, not who clicks merge. Where a forge exists the change goes through a PR, never a direct push to main. The handshake rides the bus, not the forge: coord-engine review request <team> <slug> --of <artifact> [--head <exact-sha>] --reviewer <role> opens a durable obligation that sits in the reviewer's needs-me until their verdict file exists at the exact path the command echoes (the required token is the role passed to --reviewer; that token is what the tally credits). The pending row itself carries the artifact: in needs-me --json every review-pending row serves of and the exact head (explicit null when a legacy register genuinely lacks the field), so a reviewer dispatches from the row alone — no second lookup (OUTPUT-CONTRACT OC5). One PR has one review slug (pr-N), across every push: pass the PR URL as --of and the full 40- or 64-hex commit id as --head; re-requesting the same slug with a NEW head advances the same doc to the next round, verdicts append at verdicts/<head>--<required-token>.md (frontmatter must repeat that exact head), and review status folds ONLY the active head, ignoring superseded-head verdicts without deleting them. Legacy/non-code reviews may omit --head. A verdict that cannot be counted is REPORTED, never dropped, and the verb exits 3 — a malformed filename, a verdict: token outside review.accepted_vocabulary(), or a shard whose frontmatter attests a different head each name the rule that skipped them; the failure class is the old affirmative pending_required: [alice] while alice's verdict sat unreadable in the directory. The request is durable-first, not atomic: the doc lands FIRST, then one directive per required reviewer (a verb-opened review fires each reviewer's inbox — never hand-send a review tell); a partial notification failure is loud (rc 1, naming who was and wasn't notified) and re-running the SAME request is idempotent recovery, while a re-request with a different of/required-set/requester is a loud rc 1 conflict and a present-but-unreadable doc fails closed (never overwritten). coord-engine review status <team> <slug> computes APPROVED/CHANGES/PENDING and gates the merge; coord-engine review merge-ready <team> <slug> [--notify <merger>] adds the forge half before the click (PR head == register head == verdict head, CI green; rc 0 READY / 2 NOT READY / 1 UNKNOWN) and never merges; a host without the GitHub CLI is UNKNOWN without "retry", and a gh that is some other client (its gh --version does not begin gh version) counts as none. The <artifact> is an opaque ref, so the handshake works with any forge or none — a forge-only "Approve" does NOT count (co-located agents often share one forge account); the bus verdict, keyed by agent identity, is the source of truth. The verdict FILE discharges the obligation; the ack is inbox hygiene and targets the review-request directive by its inbox id (review-request-<review-slug>-<hash>), never the bare review slug. Full rules and per-harness wiring: fulcra-agent-review and fulcra-agent-automation.
  • Park for a successor only on pushed-and-verified state. A continuity checkpoint is a promise: never park asserting repo/artifact state you have not pushed AND independently verified — git ls-remote the exact ref and compare the exact hash (a push --dry-run only proves write permission, not that the remote has your state; the memory of having pushed proves nothing). If a migration/import is still pending at park time, the snapshot says IMPORT NOT DONE plus the exact recipe and the access prerequisites; it names ONE canonical home per artifact, never candidates. The parking agent also writes the role doc if it's missing and carries an operator pre-flight checklist (egress, auth tap, repo scoping, write perm) so the successor's setup is one pass, not a serial discovery-by-failure. Full doctrine + checklist template: fulcra-agent-continuity "Parking for a successor"; cloud repo-scoping wall: HARNESS-MAP wall 11.
  • A lapsed lease is not proof a role is unattended. roles status classifies from lease timestamps alone, so its predicate is "has a lease been renewed" while the alarm reads "is anybody doing this job" — those diverged for four days (a reviewer's lease went stale while it filed verdicts hourly, and the sweep filed a false P1 per role per day). Escalation now takes a TRI-STATE attended: True suppresses it as LEASE LAPSED, ROLE IS BEING SERVED, False escalates as UNATTENDED, and the default None still escalates but must say attendance not checked rather than assert absence. Pass roles status --check-attendance (opt-in: one listing per review, budgeted and reported as scanned N/M) before calling any role unattended. The JSON attendance fact distinguishes the unrequested NOT_RUN state from a requested, budget-truncated UNKNOWN scan; that requested incomplete check exits 3 and makes the public-read envelope UNKNOWN, so automation cannot mistake a nested unknown for a clean role decision. roles status also seals lease assignment and holder presence into one liveness_fact, including both observations and both store-prefix provenance fields. Fresh presence plus a stale lease is LAPSED (or UNKNOWN if the observations cannot be sealed), never confidently VACANT.
  • Park a role, don't mute the sweep by hand. Deliberately leaving a role unattended (a reviewer on leave, seasonal on-call) is an ENGINE fact, not an agent-side convention: set dormant_until: <ISO> in team/<team>/roles/<role>.md, and while that date is future the mechanical escalate sweep suppresses the role's vacancy escalation on every heartbeat host and roles status reports DORMANT (until <ts>); escalation resumes automatically past the date, a live lease still shows HELD, and a garbage dormant_until fails OPEN (noted on stderr, escalation still fires) so a typo can't silently mute a role — see fulcra-agent-roles.
  • Fold text is capped; the task doc is the payload's home. Summaries rows bound title/description to COORD_SUMMARY_TEXT_CAP (default 280 chars, ellipsis-marked), so inbox/briefing/board show enough to triage, never the full body of a long directive — read the task doc (team/<team>/task/<slug>.md) before acting on one.
  • Engine surfaces any bus reader must honor. Two invariants a reader lives by:

    • Slug dedup + delivery rc. Every directive slug carries a payload hash (<title-slug>-<sha256(payload)[:8]>), so identical resends dedupe by construction and distinct messages can never share or clobber a slot: rc 0 directive <slug> already delivered is a deduped identical resend, and rc 1 cannot verify delivery, retry means the slot was unreadable — never overwritten, safe to retry.
    • The review/forge legs are projection-first, and they SAY so. briefing/needs-me serve the reconcile-built reviews/forge sections of _coord/summaries.json in zero extra ops when fresh, and emit a trailing review-source/forge-source row disclosing it (source: projection + as_of, or source: raw-scan + the reason: stale / incomplete / malformed — duplicate slug rows and impossible settled combinations are malformed — / unrecognized). A projection that cannot be served falls back to the full raw scan LOUDLY; it is never silently served as current. Reconcile publishes review + forge as one complete generation: a budget-cut or failed build refuses the compatibility-cache write and leaves the last complete generation current. The publication authority is _coord/projections/current.json: a builder write/read-verifies immutable generations/<digest>.json first, then writes and read-verifies the digest-bound manifest. Required UNKNOWN/incomplete sections or an unattested feed frontier stay recovery progress and never advance current; reconcile exits nonzero. Private review/forge recovery is keyed by the content-bearing public projection base, not by a detector watermark or batch digest; positive feed changes invalidate only affected review rows, while forge is rebuilt from current canonical inputs. A transport that proves conditional-write support uses CAS to fence a moved pointer. A transport that explicitly declares CAS unsupported may use one last-writer-wins manifest write only after the complete deterministic immutable generation verifies, and must verify the exact manifest read-back; missing/invalid capability and write/read failure remain nonzero. Because a non-CAS writer can race, the mandatory public-read freshness overlay rejects stale manifests before v2 authority activates. summaries.json remains reader compatibility during migration; new readers validate the current generation before use. The shared v2 public-read authority validates the exact current manifest and immutable digest, then obtains one bounded at-least-once feed window over [watermark - epsilon, now - epsilon]. It deduplicates update identities, applies only supported task deltas, and re-reads the mutable pointer before rendering. Unsupported canonical changes, unproven epsilon/feed coverage, a raced pointer, or a skipped overlay are typed UNKNOWN/NOT_RUN and nonzero — never clean. JSON and text name the same generation, source watermark, attested coverage horizon, and sorted surface coverage; JSON is still exactly one value and preserves the domain result beneath result. Immutable section values are structurally validated before dispatch: inventory records cannot be missing, malformed, outside their canonical namespace, or non-string, and content/frontmatter/type must agree. Presence is exactly presence/<file>.md; acknowledgments and responses are exactly _coord/acks/<slug>/<file>.md and _coord/responses/<slug>/<file>.md. Canonical slugs match [a-z0-9]+(?:-[a-z0-9]+)*; canonical leaf names start with an alphanumeric, contain only alphanumerics/_/-, and end in one final .md. Dot/traversal segments, file-shaped intermediate components, hidden leaves, and the legacy singular response/ namespace are not authoritative coverage. data-updates record counts are detector signals only, never cardinality, a diff, a threshold, or an identity. Live data-updates omits zero-record types, so the configured channel absent from a well-formed data_types map is a zero signal; a malformed count or unreadable authority stays UNKNOWN. Live measurements persistently showed 2721 -> 9, 1444 -> 0, and 2737 -> 25 count/enumeration pairs. A positive signal therefore requires a bounded attested enumeration with at least one immutable identity; positive-with-none is UNKNOWN/nonzero. A zero signal is not proof of CLEAR: a bounded enumeration must prove the whole outer feed window. The outer feed must attest the exact requested boundary — after, or the start_time that fulcra-api data-updates (0.1.46+) actually emits, with through/end_time as its frontier; an envelope with neither takes the named boundary recovery — and the record cursor must repeat that boundary and reach or pass the outer frontier. A missing, lagging, mismatched, or incomparable horizon is UNKNOWN, advances no watermark, and leaves freshness overlay NOT_RUN/nonzero. With today's CLI the record leg is never attested — get-records answers JSONL with no after/through, so the transport returns no window — and an unavailable or incomplete record window with an attested outer window takes the named full-scan recovery (re-anchoring under the complete-task-read gate). So on current builds every reconcile pass is a full-scan recovery; the trusted incremental path waits for an endpoint that attests the record window. That recovery keeps the tasks whose latest lifecycle state in the attested feed is an upload (collapsed by instant, so an upload later deleted or archived in the same window is not one) as references, so an rc-0 partial task/ listing that omits one fails closed (no publish, no re-anchor). A mismatched or unparseable record window stays non-recoverable. Bootstrap is complete only when an outer after/start_time supplies its boundary and the record cursor covers the same full frontier. An EMPTY start_time/end_time window wider than the corroboration bound while corroboration is dormant is UNKNOWN (FEED_WIDE_EMPTY_UNPROVEN) and takes the named full-scan recovery, never a trusted CLEAR; after/through keep the dormant default. That recovery re-anchors the persisted cursor to the server-attested end_time (attested_frontier, never a trusted watermark) only when the task fold is complete — every listed task READ this pass (any read failure keeps the prior cursor; a read-but-unparseable shard is deterministic and does not) — and an aborted or projection-refused pass never writes summaries.json, so it cannot move the cursor either. Boundary/frontier-unknown recoveries keep the prior cursor. Enabling corroboration by default is not built yet. Review projection v3 rows carry the full direct-query tally; one shared validator requires of/head, unique row slugs, settled invariants, and all three orphan/tombstone slug lists before producer carry, publication, or consumption. V2 carry rows and v1 settled caches are rebuilt before publication. The caller's OWN head is feed-gated too: with a clean data-updates window, only caller-owned slugs named changed since the projection anchor are raw-tallied; unchanged caller-owned slugs are served from the projection. Without positive feed proof, every caller-owned head slug is raw-tallied fail-closed (see the head-budget rule below). No source row at all means the aggregate carries no projection: the pre-projection raw scan. Contract for readers: docs/coord/BUS-V3.md → "Where a fold's answer came from". Ship-gate: any new projection-served fold emits a source row through the shared renderer.
    • Honor every degraded row; never read a bounded fold as complete. briefing/needs-me bound each section under COORD_BRIEFING_BUDGET (default 60s, cumulative across sections) and emit a {scanned, total, skipped} degraded row per section (review-fold-degraded, forge-degraded, presence-degraded, plus the public-read markers below). On ANY of them, fall back to the section's direct sweep (review status per slug, forge feedback, presence show — per-section fallbacks in fulcra-agent-review and fulcra-agent-automation). The review sweep itself fails closed: review status returns rc 1 (tally unknown, retry) when the doc, the verdicts listing, or any shard is unreadable, rather than printing a partial APPROVED — a degraded transport can never green-light a merge.

    These budgets rest on hard per-op boundedness: every transport subprocess runs in its own process group and is SIGKILLed whole on timeout; the per-op bound is COORD_TRANSPORT_TIMEOUT (default 30s) — run it TIGHT on a resident bus reader (e.g. 8s). Every COORD_* tuning knob, the shared positive-finite parse policy, and the FULCRA_COORD_* legacy-prefix rule are catalogued in packages/coord-engine/README.md → Environment / tuning; the mechanics that spend the budgets live in coord_engine/budget.py. Ship-gate: a NEW bounded fan-out uses budget.Deadline for its deadline check (never a hand-rolled time.monotonic() >= deadline) and budget.degraded_row for its marker, so the whole family keeps one >= boundary and one degraded shape. Undecodable CLI stdout/stderr is normalized to TransportError, never replacement-decoded; classified reads report error, not content or absence. A malformed source remains unreadable and needs repair; this does not prove a clean fold.

  • Ship-gate: a verb that mutates durable state does not ship on decision-function tests alone. It ships with at least one test that invokes the ACTUATOR end to end, or with a recorded live dry run against a real team. review residue shipped its decision function under thirteen passing tests while the command itself was dead on a NameError — model is imported locally in cli.py and the verb used it unqualified. Nothing in the suite touched the command, so a green suite sat over a completely broken verb; only running it against the real team found it. A green suite over a broken command is the same false-clear as an empty queue over 257 owed obligations: the instrument answered a question nobody asked. When you add such a test, VERIFY IT DISCRIMINATES — neuter the wiring and watch it fail — because a test that passes either way is the thing it was written to prevent.
  • The public-read failure contract — UNKNOWN is loud, never a clean-empty. Every aggregate-backed public read (status, board, needs-me, search, inbox, the agents/digest/asks/ briefing bundles) folds the summaries index via _load_rows_status, whose ok bit is False when the index/listing is UNKNOWN — as distinct from a genuinely-ABSENT index (a fresh team), which is a real, readable empty. A read whose ok is False must NEVER return a clean-empty result: it emits the shared marker _read_degraded_row(reason) = {"type": "read-degraded", "reason": …} (inside the one --json value; a stderr notice in text mode) while retaining any partial rows, and reason preserves every independent failure in the pass. The hazard it closes: a silently-empty fold reading "all clear" while a live unacked directive is merely unreadable. Ship-gate: a new aggregate-backed read consumes _load_rows_status (never a fold that drops its ok bit) and surfaces the marker on ok is False, with a red-first test asserting no clean-empty under a degraded transport.
  • --json purity: stdout is ALWAYS one parseable value. Under --json, NO prose ever reaches stdout — every degraded/notice line becomes a JSON row or a reserved key, or goes to stderr. Each fold verb's --json branch is exactly one json.dumps of the single result; threads emits a single JSON array (the dropped list + a trailing threads-degraded element), NOT JSON-Lines. Ship-gate: a new --json path is one json.dumps, with a red-first test that json.loads(stdout) yields exactly one value on every degraded path. Enforced by PARSER DISCOVERY, not a hand-kept list: test_json_purity.py walks the real parser for every --json path and fails until each is in _JSON_PINNED (smoke-run under a corrupt index AND squeezed budgets) or _JSON_EXEMPT with a stated reason — _JSON_EXEMPT is empty today, pinned paths must print SOMETHING, and the widened sweep immediately found a live leak (headroom --json printed prose on its no-accounts early return).
  • Digest uncertainty travels with the payload. digest text, stored body and timeline note must carry the same read-degraded reason and last-known/unverified row warning as JSON; an unreadable index never licenses "no open work". Its additive source timestamp/age uses summaries generated_at or, on the validated generation path, the attested coverage horizon, never the render clock as a fallback. Preserve first-written window snapshots, but withhold their pending unqualified historical timeline body while the current read is degraded; render a current warned note instead, preserving same-ID retries and already-confirmed emissions. A False store/emit-marker write or mismatched readback cannot be reported as confirmed persistence; UNKNOWN marker reads preserve existing history and withhold emission.
  • A finished review does not close its request row unless something closes it. The review store and task board need explicit closure propagation. The DECISION verbs (review close, review conclude) close their own rows at settle time — best-effort and loud, because the marker is durable truth and bookkeeping must not fail a verified closure, but a silent skip rebuilds the backlog. The review residue verb (DRY RUN by default) closes the rest on a schedule. It is permanent infrastructure, not a backfill: a review that settles through the fold's APPROVED cache is settled by a pure build path that must not mutate task state (projection.py calls transport.write exactly once in the whole module and never touches task/), so those rows have no decision verb to hook. Retiring it needs the successor where the cache writers EMIT and reconcile folds the close — and when that lands, review residue is deleted, not kept as a second reader.
  • Ask review_gc.TERMINAL_MARKERS, never a marker filename. There are three — .gc-closed, .concluded, and .settled — and .settled is deliberately outside that set because it carries an APPROVED CLAIM that some readers act on rather than merely skipping. Hard-coding names is what hid .gc-closed for a whole round; it then hid .concluded from a residue census written by someone reading the very comment that forbids it. A reader that acts on .settled's claim goes through review.settle_shortcircuit; presence alone closes nothing.
  • .settled carries TWO things and only one of them is disposable. state: APPROVED is a tally CACHE — cheap to recompute, safe to drop. state: MERGED + merge_sha is merge EVIDENCE written by review close, and nothing recomputes it. review status deletes a stale cache but never a MERGED marker; an unreadable marker is left alone, and an unclassifiable one (including an unrecognised state: from a future writer) is PRESERVED, reported on stderr, rc 3 — only a POSITIVELY identified cache may be deleted. If you add a writer to a shared marker path, audit every existing deleter of it in the same change.
  • A cache may only bind to evidence it can actually fingerprint, and EVERY reader applies the same rule. The .settled cache carries an evidence digest over the verdict shard NAMES, recomputed from the current listing before it is honoured — but a name digest cannot see an in-place rewrite of a plain <head>--<reviewer>.md shard, and this store exposes no etag or content hash in a listing. So a directory holding any plain shard gets no cache at all (folded for real, every time; append-only directories keep the fast path), both writers refuse to stamp a marker no reader may honour, and every reader goes through ONE decision function, review.settle_shortcircuit — the fan-out once skipped on marker PRESENCE alone and hid a pending reviewer's obligation. MERGED markers short-circuit unconditionally. The projection tier ABOVE the readers is a reader too: its zero-op settled carry may only be taken by a row whose ev_bindable is True; everything else demotes to one listing whose fingerprint compares name+size+mtime per shard and refuses any unclosed minute. When you add a validation rule to a reader, enumerate every tier that can answer BEFORE it.
  • escalate attendance: one shared scan, and partial coverage is NOT an incident. The vacancy sweep answers "did a holder file a verdict recently" from ONE _verdict_activity_index pass built before the role loop, bounded by BOTH a count (budget, 40) and a wall clock (COORD_ATTENDANCE_SCAN_BUDGET, 30s) — a count alone cannot bound time. The review register is far larger than the budget, so coverage is always partial by design: the stderr envelope reports attendance=N/M rather than alarming, and rc 3 is reserved for a WALL-CLOCK cut — a real anomaly.
  • Prior freshness affects fold cost. A STALE prior requires additional reads and may exhaust the budget. Because forge completeness follows the review fold, a stale prior can leave both aggregates incomplete. A SMALL unknown remainder is retried once inside the same pass (RETRY_UNKNOWN_MAX, bounded by the SAME deadline object); a tolerance that calls one-short complete was explicitly REJECTED — it manufactures the false-clear this file keeps warning about. A fold "stuck" at n-1 of n is usually a transient, not a broken record.
  • Never hand two builders ONE budget object. A single Deadline shared by the review and forge projections let the review fold spend it first, so forge was not slow — it was never built: a section that always runs last inside a shared budget starves deterministically and silently. Each builder opens its own (COORD_PROJECTION_BUILD_BUDGET, COORD_FORGE_BUILD_BUDGET); worst-case pass duration is their SUM, stated rather than hidden. Completeness coupling is different from budget coupling and must not be "fixed" with it — forge's complete still follows the review fold's.
  • A DELIVERY path may never lose coverage to a FORMATTING failure. A queue renderer that raised on a malformed event once skipped the cursor save, wedging the cursor on the same poison event forever without an error report. Two layers, because the field fix alone guards the instance and leaves the class: rendering is PER EVENT and cannot raise — poison renders as an explicit, COUNTED POISON line (trading a crash for a disappearance is the worse bug) — and the cursor save lives in a finally: once a window has been READ, coverage is a fact about what the process RECEIVED. peek stays the one exit that deliberately does not advance. When you add a step between a read and its acknowledgement, ask what happens to the acknowledgement if that step throws.
  • Head-of-line: a budget cut may only ever truncate the TAIL — never the head. The work-discovery folds do live per-op transport at query time over an unbounded population; under budget pressure the cut must land on the lowest-priority tail, so an agent's OWN assigned work and any decision parked on a human can never be the thing that goes invisible. Two structural heads enforce this:
    • Blocked-on-human is the reserved FIRST section, and it is FREE. briefing and needs-me render open rows blocked on a human first, computed by query.blocked_on_human PURELY from aggregate rows already in memory — zero extra transport ops, and free is what makes it un-starvable. --on-user TYPES the block as blocked_on: user:<name> (additive; legacy plain values resolve against the caller's already-loaded identity set), and ambiguity resolves toward SURFACING — a hidden human-blocked item is the incident, a false positive only noise.
    • The caller's own reviews are the review-fold head, on a budget earlier legs cannot have spent. _pending_reviews_for derives the caller-assigned review slugs for free from the review-request directive rows and scans them FIRST under a DEDICATED deadline_seconds, NOT the shared briefing budget's drained remainder (the fix for a live scanned 0/N: the leg used to start already expired on a busy board). The tail keeps the shared budget; truncating it is expected and reports review-fold-degraded. A head that STILL cannot complete is UNKNOWN and gets its OWN DISTINCT marker review-head-degraded — on ANY non-complete outcome: a budget cut, an unreadable review doc, a per-slug TransportError, or a caller-directive slug absent from the listing (fail closed — negative membership in a listing is not proof the obligation is gone; missing slugs are named in a missing field). The two markers carry PHASE-LOCAL counts and never borrow each other's numbers (an UNKNOWN head reads 0/1, never 0/0 or 1/1); a HEAD-only incident emits review-head-degraded and NOTHING else. Ship-gate: a new bounded work-discovery fold puts blocked-on-human and caller-assigned work at the head (free where the data is already loaded; a dedicated budget where it is not), proves the head completes under a spent shared budget, and gives "head could not complete" a marker distinct from "tail truncated."
    • Every marker must RENDER, not just exist: briefing and needs-me type-dispatch every review row type they can receive through ONE shared helper (_review_row_line), so an identical row type can never diverge between the two verbs. An unknown/typeless row must NEVER reach the generic task line (which prints [ ?] ? None on a marker shape); a degraded/UNKNOWN marker is always shown and NEVER counted as a pending item. Ship-gate: a new review row type joins the shared dispatch with a red-first test that both verbs show its real line and that an UNKNOWN marker is not tallied as pending.
  • Role routing is the same contract, one layer in — a role you hold is an address. A directive assigned to a ROLE is directed at whoever holds a fresh lease on it, so briefing, inbox, and needs-me all fold role-routed work into the holder's queue (that is what makes role-based identity outlive a session). ONE resolver: cli._held_roles_for_rows — never resolve roles a second way, or the folds silently disagree about a lease. It returns (held, unresolved), and unresolved is the load-bearing half: a role whose lease state is UNKNOWN (transport failure, unreadable lease shard, unparseable role doc, an explicitly invalid sla_hours, or a budget cut) is neither held nor not-held — folding it into an empty held-set renders a clean, role-blind queue indistinguishable from "you have no role work". Every caller surfaces it as _role_degraded_row = {"type": "role-degraded", "roles": […]} plus the text line. Ship-gate: a new fold that answers "what needs this agent" resolves roles through that one helper and surfaces unresolved, with a red-first test proving a failed lookup is visible. Only a complete, successfully parsed listing is negative membership evidence — a failed read and a failed parse are the same fact, and the rule reaches into the FIELD: an explicitly invalid value is UNKNOWN (a default is never a substitute for a value someone set and got wrong), while an absent/blank optional field means the default IS the stated intent. Fold that distinction ONCE, in roles.py, and let callers fail closed on None. The ship-gate extends to write paths: continuity park once swallowed a failed listing as "you hold no roles", printed "nothing to park", and exited 0 — silently discarding the checkpoint the next session resumes from. _held_roles now returns (held, ok); on ok is False park fails non-zero saying the checkpoint was NOT written, and a complete fold proving zero fresh roles exits rc 2 CHECKPOINT NOT WRITTEN — a command that ACTS on the roles you hold refuses to act on UNKNOWN rather than treating it as "nothing to do". The fold's candidate set is the union of role documents and role-lease directories, deduplicated by role; a lease directory whose role document is absent/unreadable is UNKNOWN, not evidence that no role exists. If any selected role snapshot or checkpoint-ref write fails, park exits non-zero after attempting the remaining roles; rc 0 certifies that every selected save completed. The fold's cost is one roles/ listing + a few ops per role the open work references, and it runs under one cumulative COORD_ROLE_FOLD_BUDGET (default 20s) — a cut marks every unfinished candidate unresolved, never "not held".
  • Presence engagement is an additive, defensively-parsed schema. A presence shard MAY carry an engagement object with exactly four qualified names: engagement.mode (resident|session|occasional), engagement.until, engagement.state (active|lapsed), engagement.lapsed_at. Absent engagement reads as resident + active — every legacy shard is unchanged, and a beat with no --engagement flag writes NO engagement field (byte-identical legacy shard, pinned). --engagement session defaults until to beat time + 8h; --until is meaningful ONLY for session (anything else is rc 2, nothing written). A beat is REFRESH-SAFE and must never manufacture liveness: a session beat reads its own prior shard first — an ABSENT prior (disproven by one parent listing; the transport read is None-on-any-failure, so the listing is the disambiguator) is a fresh session; an UNKNOWN prior (listed-but-unreadable shard, failed listing) FAILS CLOSED at rc 1, so a transient read failure never lets fresh active engagement replace a sweep-marked lapsed session; a readable prior with malformed engagement self-heals as fresh. A continuing session's resolved until is PRESERVED (recomputed only for a genuinely new session; an explicit --until wins) — sliding it forward on every beat would make a session never lapse. The beat never writes engagement.state/engagement.lapsed_at to a non-default value — those two names are written ONLY by the lapse sweep (below), and clearing lapsed takes an explicit session re-declaration. Every fold PARSES engagement through the ONE defensive seam presence.parse_engagement(fm) — any malformed input (non-dict, unknown mode/state, unparseable timestamps, a session with no resolved until) degrades to the legacy resident/active default AND sets a visible _engagement_degraded marker, never raises — and only the liveness combiner (below) acts on it; the pure classify never consults it. Ship-gate: any engagement read goes through parse_engagement (never a raw dict-walk); any new bad-input class gets a red-first degrades-with-marker test; no write path but the lapse sweep sets state/lapsed_at.
  • Activity implies liveness. Every engine bus WRITE verb refreshes the actor's presence timestamp, so a working agent is provably live — distinct from a dead session whose launchd beat still ticks (the liveness combiner consumes this as proof). Membership is a DENYLIST: every verb refreshes EXCEPT the declared reads (status/board/search/needs-me/briefing, presence show, review status, queue, health, doctor, obligations, roles status, continuity resume) and the plain presence beat. It was once an ALLOWLIST of functions, which could not keep this paragraph's promise — a verb added later was simply absent, and absence there is indistinguishable from "this agent is not working". Many write verbs had drifted outside it (review close, escalate, continuity snapshot/park, roles claim/release, answer, bus-v3 send, stash push …), so an agent whose job IS reviewing rendered stale — nudge while working. Roster liveness can trigger follow-up work, so active writers must not be omitted from coverage. The work axis. Verb coverage alone cannot see work that never passes through a verb (report docs are written straight to the store), so presence.liveness also takes work_ts (newest work-artifact time, read-derived by the caller) plus a three-valued work_scan (NONE|COMPLETE|PARTIAL): NONE → byte-identical legacy behaviour; COMPLETE → absence is a real finding (no work found); PARTIAL (budget ran out, unreadable listing) → no imperative at all, because the refuting artifact may be in the unscanned part — list_dir cannot tell an empty directory from an unreadable one, so only a COMPLETED scan licenses an absence reading. presence show and briefing measure, both bounded (COORD_PRESENCE_WORK_BUDGET, default 20s; NB env_float is POSITIVE-finite — a 0 falls back to the default, it does not disable). Scan order is load-bearing: agent reports (a handful of listings) run BEFORE the review sweep (hundreds) — with reviews first, the sweep consumed the whole budget and PARTIAL muted the nudge fleet-wide. The sweep is now the POINTER-LESS FALLBACK only: per-agent work EVENTS (_coord/agents/<agent>/work/<iso>-<digest>.json) answer the read-side question in one listing + one read per agent, and are IMMUTABLE ON PURPOSE — the store has no conditional or versioned write, so a shared mutable pointer cannot be defended (review reproduced an older stamp clobbering a newer one, and a delete-on-failure that could erase another host's fresh write). A writer only CREATES its own event, "newest" is a deterministic fold over ISO-led names, and a failed write leaves prior events intact (slightly stale, never wrong) — NEVER add a delete-on-failure here. Four pinned rules: ONE write site (the activity chokepoint, so a new write verb stamps by default); refusal semantics (stamped only on rc == 0, monotonic, missing/corrupt is UNKNOWN and never "did nothing"); transitional (a pointer-less agent falls back to the sweep); attributable (kind + path). NB the pointer is keyed by the RAW agent name, NOT tasks.agent_key() — the hashed form would file every pointer where no reader lists. The continuity audit deliberately does NOT consume work evidence: "working but not snapshotting" is precisely its finding, and the asymmetry is chosen. Classification is PER-OPERATION, not per-function. Several handlers serve both a read and a write: queue TEAM vs queue commit TEAM (and --consume, which advances ANOTHER agent's cursor), inbox TEAM vs inbox --ack, digest TEAM vs digest --store. Keyed on the function alone these were wrong in BOTH directions at once — queue commit recorded durable classifications without counting as activity, while inbox and digest refreshed presence merely by being VIEWED. _MIXED_MODE_ACTIVITY maps such a handler to a predicate over the PARSED ARGS, and _is_activity_invocation(args) — not the function-only helper — is what dispatch calls. Verdict shards are APPEND-ONLY (standing ruling). Two forms are first-class, permanently: <head>--<reviewer>.md (hand-writers, unchanged) and <head>--<reviewer>--<iso>-<digest>.md (the verb) — the store has no create-if-absent and no versioned write, so writing a SHARED name is check-then-write and cannot protect evidence (a concurrent CHANGES was reproducibly overwritten by APPROVE at rc 0); a unique name touches no existing file. Every register reader folds newest per (head, reviewer), ties break on the name, and supersession is never silent (superseded_verdicts is reported). A correction is a NEW shard, and a new verdict INVALIDATES the settle cache — only the cache (the evidence-binding rules above); a state: MERGED marker survives a late verdict. Every reader dates a plain shard the same way: filename ts, then frontmatter ts, then normalized listing mtime. review verdict exists so that filing a verdict IS an engine write (it was the one act with no verb, which left reviewers invisible to every liveness fix). It is SUGAR over the same artifact — it writes the append-only <head>--<reviewer>--<iso>-<digest>.md form in the round's verdicts directory, and DIRECT shard-writing of the plain form stays valid. It never overwrites: the name is unique, so a second filing is a NEW shard that supersedes the prior one (below), never a replacement of evidence a merge may rest on; a changed head is a new round. Every registered command must be CLASSIFIED, read or write or mixed: tests/test_activity_covers_every_write_verb.py walks the real argparse tree and fails on any unclassified command (a regex cannot decide this — several verbs persist only through helpers). _ACTIVITY_READ_FUNCS is completed at module end, after the extracted command modules import — assembled earlier, it let view verbs refresh presence merely by being READ, the worse direction because it suppresses the nudge for an agent who really is gone. The hook lives at the single dispatch chokepoint, fires only on rc == 0, and the actor is the WRITER (--from / FULCRA_COORD_AGENT; the anonymous reconcile fallback is not a presence identity). Two pinned constraints: THROTTLE — at most ONE presence write per presence.ACTIVITY_REFRESH_INTERVAL (60s) per process, via a monotonic-clock memo; and FAILURE ISOLATION — a refresh failure never fails the successful bus write (one stderr note, rc untouched). The refresh is a TIMESTAMP BUMP, not a beat re-run: it rewrites ONLY the top-level timestamp line and preserves every other byte verbatim, so it never slides a session's until and never writes state/lapsed_at (sweep-owned). The minimal-beat fallback fires ONLY on list_dir-CONFIRMED absence and FAILS CLOSED on any UNKNOWN — failure isolation never means destructive fallback. Ship-gate: the throttle memo is process-global state — reset it between tests; a new write verb is activity by default (denylist), a new READ verb joins _ACTIVITY_READ_FUNCS, and a mixed handler joins _MIXED_MODE_ACTIVITY; the preserve-everything-but-timestamp rule stays red-first pinned.
  • A CHANGES is lifted only by a shard that NAMES it (supersedes:), never by the clock (2026-09-05, codex-coder, review-winning-envelope r4). Client timestamps cannot carry the correction contract: a CHANGES filed later from a host whose clock is behind sorts EARLIER, the old APPROVE wins, and a ship gate validates withdrawn consent. The fold is now: a shard is RESOLVED when another shard of the same reviewer names it in supersedes: (validated against shards that exist); any UNRESOLVED CHANGES dominates regardless of timestamp; otherwise the newest live shard wins; equal keys and unnamed conflicts fail closed to CHANGES. review verdict names every prior shard of yours it can list; if the listing is degraded it names NOTHING and says so (your prior CHANGES keeps dominating until you re-file). A hand-written APPROVE must carry supersedes: itself. Only the STORE can supply causality (r8, both codex reviewers): a name is predictable, and a client-written nonce is editable frontmatter at a mutable path (a plain CHANGES rewritten in place kept its nonce and an old edge still resolved it; a predeclared nonce was matched by a later CHANGES). An edge name@sha256:<digest> is honoured only when the digest matches the target's CURRENT bytes AND the store's server-assigned mtime proves the target strictly earlier than the superseder — same minute or unknown fails closed; a bare legacy name needs the same mtime proof. The verb quotes the content digest of each prior it can list AND read; a prior it cannot read is not named; on a degraded listing it names NOTHING (if you cannot enumerate the priors you cannot claim to supersede them). The random nonce: also feeds the digest in the shard NAME, so identical same-second filings cannot collide. Invalid edges: a shard can never resolve ITSELF (a self-link let a CHANGES erase its own withdrawal); self-links and names that resolve nothing are reported in the tally as malformed_supersedes, never folded around silently; a cycle fails closed to CHANGES; a forward edge cannot be forged (the name embeds a content digest). This amends ruling b99fb8da (newest-wins): constraint 5 — a stale CHANGES must not block forever — is satisfied by the link the verb writes, not by the order of the clock.
  • Same-second verdict shards order by chronology, not digest (2026-09-05, both codex reviewers, coord-fold round 12). The append-only name has SECOND precision plus a content digest, and the fold broke same-second ties on the name — so an earlier APPROVE could outrank a later CHANGES from the same reviewer (reproduced: digest feb86aee over 058ddb93). Now review verdict writes a microsecond ts: in the shard frontmatter and the fold orders every shard by review.canonical_sort_key — the second from the ACL-controlled NAME (frontmatter can never move a shard across seconds), the fraction from frontmatter only within that second, .000000 for shards without one so legacy and new compare in ONE format. review status --json now carries winning: {reviewer: {name, verdict, sort_key}} — the exact shard the fold kept. A downstream consumer (a ship gate) reads winning; it never refolds filenames itself. The projection (projection.py) uses the SAME key and records winning in each generation row, and the generation-backed review status fails closed (rc 3) on a row without it — two canonical readers must not answer differently about one directory. Caveats, pinned by test: two legacy shards with no ts: in the same second still tie on the name; the verb samples the clock ONCE for both the name's second and the frontmatter fraction (two samples let a verdict straddle a second and lose to an earlier same-second shard); and the resulting order is client-timestamp order, not a provable arrival chronology — cross-host clock skew is out of the fold's reach, and two shards with equal microseconds tie deterministically on the name.
  • Engagement-aware liveness is a combiner over two ORTHOGONAL axes. classify(ts, now) stays PURE — freshness only (live/idle/stale), a function of the timestamp alone. The truth table is layered on top by presence.liveness(shard, now=…), which returns {state, freshness, annotation, engagement}. STALENESS (timestamp freshness) and DORMANCY (a session past its until, boundary-inclusive, OR a durable sweep-written engagement.state: lapsed) are INDEPENDENT and rendered as two facts, NEVER a merged label: a dormant shard renders primary state LAPSED — distinct from stale/dead, EXPLAINED, ROLE-RETAINING — with the freshness axis in the annotation (a session overrunning its window while beating is honestly LAPSED+active, a nudge to extend, NEVER silently live). A degraded engagement reads as the legacy default and can never manufacture dormancy; all agent lookups match by EXACT id (no substring/fuzzy). The verdict rides ADDITIVELY: roster rows keep liveness = the pure freshness band (existing callers read it; its meaning must not shift) and gain state/freshness/annotation. engagement gate <team> is the deterministic mixed-fleet gate: every LIVE roster agent is COVERED iff it beats with well-formed engagement OR appears in the operator map _coord/router/engagement-defaults.json; PASS iff all live agents COVERED. READ-CONTRACT LENS (mandatory): transport.read returns None on BOTH missing and failure, and a list_dir degradation must never fold to empty, so a falsy read/listing is NEVER "confirmed absent" on its own — an UNKNOWN on either of the gate's reads (the defaults file, or the presence ROSTER via _presence_shards_status, which preserves degradation instead of swallowing a TransportError to []) is DEGRADED, fail closed — never PASS on unknown coverage (an empty gate passes vacuously, so an UNKNOWN roster must never look confirmed-empty; an unparseable shard is UNKNOWN coverage, never a synthesized phantom row). Only a CONFIRMED enumeration may PASS; a confirmed-EMPTY roster still passes vacuously. The vacancy/escalation SEMANTIC change is gated, and the gate ships dormant by default — enable it explicitly: LAPSED rendering lands unconditionally, but reading a LAPSED session role-holder as EXPLAINED ABSENCE (suppress the vacancy escalation with a note) activates ONLY when _engagement_gate_passes(team); otherwise behavior is today's, verbatim. BOTH branches are red-first pinned. Ship-gate: classify stays pure; any new dormancy/coverage input class gets a red-first test; the gate fails closed on any UNKNOWN; the gated semantic change keeps both branches pinned until the gate is satisfied fleet-wide.
  • The zero-token lapse sweep writes two fields and nothing else. coord-engine engagement sweep <team> is a host-tick, model-free pass that marks a session past its until as LAPSED by writing EXACTLY engagement.state: lapsed + engagement.lapsed_at into the presence shard — the ONE sanctioned exception to agent-owned presence writes, scoped to those two names. MARK predicate (presence.sweep_decision, the pure read-only seam, via parse_engagement): mark iff mode == session AND until present AND now ≥ until AND state == active AND engagement WELL-FORMED; anything else SKIPs (fail-closed — a malformed shard NEVER manufactures a lapse), and an already-lapsed session is an idempotent NOOP. The write preserves everything but the two fields — timestamp NOT bumped, until NOT slid, body verbatim — and NEVER parks, NEVER releases roles (operator decision: park is explicit-only). If enumeration raises, the roster is UNKNOWN and the sweep is DEGRADED — loud, rc 1, never a clean 0 marked; a per-shard failed read SKIPs into the degraded bucket (a failed read must NEVER cause a write); a per-shard write failure is reported and the sweep continues. --dry-run previews and writes nothing; rc 0 only on a clean sweep. Downstream consumers (e.g. a deployed router) read the marker for reduced-cadence check-ins; lapsed → active clears only via an explicit session re-declaration in the beat. Ship-gate: the sweep writes ONLY state/lapsed_at; the mark predicate stays fail-closed; enumeration-degrade is loud + rc-nonzero; idempotency and the two-field-only / never-park / never-release invariants stay red-first pinned.
  • The rc / error register a bus reader parses. Machine type fields ride the degraded fold rows (*-degraded); the single-slug verify paths are prose at rc 1, where the convention is load-bearing: the prose ends in "…, retry" iff the failure is retryable (a transient unknown — e.g. review status tally unknown, retry, roles status lease state unknown … retry, tell cannot verify delivery, retry) and names a tombstone or ABSENT iff terminal (a review status on a soft-deleted review, or on a slug that was never created — a retry never changes either). An UNEXPECTED exception is neither: the top-level guard emits a registered envelope coord-engine: error: command=<cmd> type=<Exc>: <msg> (rc 1) — the error: token distinguishes an engine fault from a retryable degrade.
  • Views never lie past the current read — the index-freshness invariant. Two mechanisms keep status/board/inbox honest between heartbeats, so a same-minute close or a between-tick directive can't leave a surface stale:

    • Same-minute-touched docs are reparsed, not reused. The store file list mtime is minute-granular, so reconcile reuses a prior summaries row only when the doc is unchanged by mtime AND byte size AND its mtime-minute is provably closed before the last reconcile read; a row stamped by an older ROW_SCHEMA_VERSION is likewise reparsed once, so a projection change self-heals the whole index within one full pass.
    • A feed delta surfaces new docs THIS read. Healthy-path folds combine the aggregate with team-filtered data-updates changes and read only the changed task docs; on any doubt the legacy freshness overlay lists the task dir once, bounded (COORD_OVERLAY_CAP / COORD_OVERLAY_BUDGET) and degrading the inbox source visibly when capped — never silent truncation.
    • Acks are folded change-driven, and reuse needs positive evidence. Reconcile asks the store what changed since the ack fold's OWN anchor (acks_folded_through, not generated_at) and re-folds only those slugs; a prior acked_by is reused ONLY when the store answered and did not name that slug — every unknown falls back to the full fold and logs why. No false advance: a fold that couldn't read what it meant to leaves the anchor in place, a failed listing preserves the prior acked_by rather than un-acking, and a forced full fold every COORD_ACKS_FULL_EVERY passes (default 72) bounds anything the query could miss.
    • Reconcile's own pass is a feed delta, not a directory scan. It consumes data-updates since a durable cursor (reconcile_cursor — watermark + processed ledger) and reads ONLY the changed shards. The full list_dir(task/) scan stays as (a) a scheduled drift self-check (every COORD_RECONCILE_FULL_EVERY passes) whose divergences are logged LOUD and rebuilt from the full scan, never silently absorbed and (b) one named recovery for an established cursor when the outer feed coverage boundary/frontier alone is unavailable or unparseable. That detector-full-scan recovery is visible in the result/log, rebuilds canonical sections (including absent generation substrate), seals the rebuilt snapshot into generation identity, and preserves the old proven watermark; it fabricates no feed advance. An absent manifest cold-starts exactly one generation; an identical later recovery reuses that generation rather than minting a chain whose only change is prior_generation_id. Every other detector UNKNOWN aborts before listing canonical tasks. An incremental row is stamped byte-identically to a full-scan row. Ship-gate: a new reconcile fast path keeps the periodic drift check, restricts recovery to that exact reason family with a prior proven watermark, and its cursor key is cut from build_aggregate's passthrough and recomputed in full every pass.
    • summaries.json is one shared doc written by many hosts at many versions — a top-level key added in version N is wiped by any host older than N, which rebuilds the document from the key set it knows and writes it over everyone else's (this is how acks_folded_through kept vanishing while any pre-passthrough host still reconciled). build_aggregate now carries unknown top-level keys through. A preserving older host that carries the projection-publication fence but cannot mint its section bindings is fail-closed by newer readers; a host older than the passthrough can still remove any fence. A general new top-level key is live only once the whole fleet is upgraded — check health before assuming a fold-state key is doing anything, and never rebuild the aggregate from a fixed key set. The same last-writer-wins shape applies to reconcile_cursor: a pass writes the cursor it STARTED from (or advances it), so a pass that began before another host's re-anchor would roll that cursor back. Immediately before publishing — on every path, including the no-change fast path — reconcile re-reads the store's cursor; if its watermark is strictly newer than the one this pass started from, the pass skips its generation + summaries write and its health shard reads advanced: false, degraded_reason: superseded by a newer cursor in the store (never "keep the newer cursor over my rows" — those rows never saw the changes in between). Equal/older writes as before; an unreadable store cursor writes as before and logs it. This is a narrowing, not a fence (no compare-and-swap, so a write can still race the re-read), and it protects only against hosts running the build that has it.

    Mechanics (stamping, deterministic cut, the reconcile reuse anchor) live with the engine — fulcra-agent-reconcile and packages/coord-engine.

  • Idle-agent parking (standing, operator-set). An agent with 48h of no work in its queue parks a continuity checkpoint to the bus (coord-engine continuity park <team> --agent <self> --objective "<what you watch>" --next "resume on directed wake or new assignment") and drops to a coarse daily check; a directed wake or new assignment resumes it (continuity resume). Dormant watchers must not burn compute indefinitely; the parked checkpoint loses nothing. Applies to every agent, the coordinator included. continuity park exits rc 2 when no fresh role is held and writes no checkpoint — treat that as "not parked", never as a clean no-op.
  • snapshot is the routine save; park means you are LEAVING. Both write a checkpoint, so it is easy to treat them as interchangeable and reach for the one a rule happens to name. They are not interchangeable:
    • continuity snapshot <team> <agent> <slug> — a PROGRESS save. This is the form for checkpoint-on-every-wake: you did material work, you are still here, here is the state you left.
    • continuity park <team> --agent <self> — a SESSION-EXIT save (its own help says so): you are going away, so snapshot every held role at once and set the checkpoint_refs. Use it at genuine handoff, at dormancy (above), and on the wake you roles claim so the new role starts with a checkpoint. Do not park on every wake — it announces a handoff you are not making, repeatedly, and drains the meaning from the one signal that should mean "this agent has stepped away".
  • park's rc 2 proves only that NO FRESH HELD ROLE WAS FOUND — nothing more. That one exit code covers two opposite situations and the fix differs: an assigned/expected role whose lease lapsed → roles claim (left unfixed the role sits VACANT past SLA and role-routed work reaches no holder); intentionally role-less (the steady state for most workers) → use continuity snapshot for progress saves, and do NOT fabricate a role merely to make park succeed. Check roles status <team> <role> before concluding which case you are in: rc 2 is a lease diagnostic, not an identity verdict. continuity resume always reports the checkpoint age (JSON checkpoint_age_seconds); use --max-age 1h when a wake or acceptance run must fail rc 2 on stale state — JSON error_code separates invalid duration, unknown age, and stale; small future clock skew clamps to zero, farther-future checkpoints fail loud.
  • Delivery rule. The human-visible report is a turn's (or tick's) terminal output — composed last, after every tool call. Text followed by more tool activity may never render ("sent" is not "delivered"), so anything that MUST reach a recipient (human or agent) goes on the bus as a durable artifact (ask, review doc, snapshot), never only in session text.
  • Backlog. A "do later" item goes ON THE BUS: coord-engine later <team> "<title>" -s "<context>" parks it on the @backlog audience (durable, visible on the board, spams no inbox); route it later with the ordinary assignment verbs. Backlog in session memory alone dies at compaction.
  • Intent-capture doctrine — a spoken commitment is filed the SAME turn. When the operator states an intent to ANY agent ("later today", "I'll enumerate that list", any commitment they own), that agent captures it immediately with coord-engine intent <team> "<text>" --for <principal> [--by <when>] — an uncaptured commitment is the drop nobody can see. Two surfaces back this:
    • coord-engine intent <team> "<text>" --for <principal> [--by <when>] — sugar over the directive path (writes an intent:<principal> item, intent_by frontmatter, hash-slug delivery + read-back inherited). Identity is text + assignee only — --by is EXCLUDED. So an identical restatement dedupes (rc 0 intent already captured), while a restatement with a DIFFERENT --by is a verified in-place window update on the same doc (rc 0 intent window updated, read-back-checked; unverifiable → rc 1, retry — never a stale deadline, never a forked item). A relative --by (5d/36h/10m) re-resolves from now on each restatement.
    • coord-engine threads <team> --for <principal> [--json] — the dropped-work fold, three mutually-exclusive modes (first match wins): started-then-silent (an item the principal owns/last-touched, quiet past --silence-days, default 3); blocked-on-operator (progress waits on the principal — assignee: <principal>, a blocked-on:<principal> tag, or a needs:human block naming them — surfaced immediately, no aging); intent-never-started (an intent:<principal> item past its window and not followed up). A terminal item (done/abandoned) is NEVER a dropped thread in any mode — the fold refuses it and reads the authoritative status from the task doc, not the summaries index (a same-minute close can leave the index stale). A threads-degraded row means the fold saw only PART of the store — sweep or wait, never trust it as complete; --json is ONE array, not JSON-Lines. The coordinator role typically runs this fold in its loop and owns the curation/push call.
  • Blocked-on-operator doctrine — a harness approval-gate is a bus event (operator order). When work waits on an operator/harness approval that only a human can grant (a "nod before you build", a deploy sign-off, an entered credential, any approval you cannot self-serve), the blocked agent does THREE things the same turn, not one: (1) immediately post a P1 BLOCKED-ON-OPERATOR shard to the coordinator role naming the EXACT approval and the EXACT artifact it gates (PR #, slug, host) — so the block is a visible, routable bus item, not a private wait; (2) continue all non-blocked work — the block scopes to the gated artifact, never to the agent; idle-while-blocked on one item when other work is ready is itself a failure; (3) keep beating — a blocked agent is still live and must stay so. Silence-while-blocked is a protocol violation: never let an operator approval turn into an invisible stall (the failure this codifies). The operator's absence is never approval — surface the block loudly and persistently, and take the other ready work meanwhile.
  • ATC (air-traffic control, alpha). On a subscription-cap fleet, consult coord-engine route <team> --needs <tags> before a dispatch to pick the cheapest model that covers the work, and log the outcome after with coord-engine usage log; the ledger feeds the headroom fold and demotes a model that keeps failing a task class. Rubric, routing procedure, and the coordinator-join surface (atc harvest, bindings, route --for-role): fulcra-agent-atc.
  • Timeline projection (opt-in). coord-engine annotate resolution <team> transitions (default off) makes the heartbeat project task transitions onto your Fulcra timeline model-free, right after each reconcile; annotate status <team> shows the level + cursor. It is the successor to the legacy first-generation annotations writer, which is now retired (see Fulcra platform surface). Projection needs the typed-record writer (fulcra-common) installed beside coord-engine (uv tool install … --with fulcra-common); without it the step is an explicit exit-0 no-op. Setup + install recipe: docs/coord/GET-ON-THE-BUS.md and fulcra-agent-automation.

Operator knowledge: vault + prefs

Long-running work with the operator accumulates knowledge about them. Store it on Fulcra the turn it is stated (the same capture doctrine that applies to intents), split by kind:

  • Facts about the operator's world — people, companies, places, pets, routines, the semantics of their Fulcra data ("a hike on X road is always a dog walk") — go in fulcra-vault: a markdown knowledge vault in Fulcra Files (live today; it also hosts the meeting CRM). Write an owned section under your agent id, add a log line, reindex; give entities their own wikilink-able notes. The CLI works from any authed host.
  • Preferences — how the operator wants to be served: tone, format, defaults, per-platform overrides — are fulcra-prefs signals (typed, decaying, confidence-weighted, deterministically compiled). If fulcra-prefs capture fails (the layer is alpha), do NOT drop the signal: store the statement as a vault note and queue the signal keys there for capture once the layer is up.
  • Retrieval, today: both layers inject at session start — vault install-hooks loads HOT.md, prefs compiles per-platform docs into the boot context. Beyond the hot set, the convention is judgment-based: when a person, company, place, or project is named in your work, consult the vault (fulcra-vault read MAP.md, backlinks) before asking the operator or guessing. Deeper retrieval (search/MCP) is future work — storage now is what makes it possible later.

Coord-engine 2.0 truthfulness boundary

The separate coord-v5 alpha is the new work-core release track, not an upgrade of the installed Python engine or an activation of the v4 cutover. Its release status separates packaging, usable operations, agent acceptance, and upstream release. Do not change an existing team's authority, schedules, or historical work when trying the alpha. Its Node runtime and explicit enrollment requirements belong to that package only; Collect and the web application are not prerequisites.

For new v5 enrollment, use the package's onboarding guide and capability-evidenced coord-v5 enrollment plan; keep one native listener registration per environment/harness. A worker keeps its own native wake until that environment's listener wake is verified end to end, and keeps it afterwards as a coarse backstop; never retire a worker wake on registration or delivery evidence alone (harness guide). Its plan is not an installed schedule or a membership grant. Current verified event ingress selects native-event without requiring a schedule/loop when read, publish, checkpoint, dispatch and explicit unattended opt-in are satisfied; a verified schedule is a backstop. A reporting listener routes attention to separate workers, while deliberate self-ticking owned-task execution is a separate opt-in mode. Planner mode is not event-adapter support or idle-wake proof. enrollment instructions accepts optional instruction_mode: worker|listener|executor; omitted and explicit worker modes produce the same managed block. Regeneration updates older managed prose while preserving surrounding text. Apply listener/executor blocks only in their own local/session instructions, not shared repository-wide worker instructions. The listener reports its own reads/routes/conflicts/reconciliation, not worker progress/completion or fabricated receiver acknowledgment. Executor work needs explicit task ownership and recovery context; a wake is not authority to adopt work. No instruction mode installs a schedule or grants permissions; self-ticking requires separate authorization. Generation/CLI tests are not proof of agent obedience. Preserve the distinction between contact, inbox observation, progress and checkpoint clocks. Role claims survive in annotation history but are not distributed locks; partial source views cannot authorize exclusive takeover. Keep private descriptors and managed workspace instructions local.

In v5, current source health can recover after a strictly newer successful read; historical errors remain in the observation journal and coverage remains partial. coord-v5 transport read journals failed observations and preserves cached work, but exits nonzero when the current read is unavailable; clean partial reads remain nonfatal and never imply absence. Use checkpoint prepare to obtain normalized checkpoint content and its canonical digest before publication; raw artifact integrity and canonical body integrity are separate checks. A receiver can run coord-v5 checkpoint verify --artifact ABS --publication ABS on private local files to measure exact raw SHA256, normalized body digest, and scope/identity bindings; this is not remote retrieval, access, native-wake, or source-completeness proof. Artifact bytes are capped at 256 KiB, publication JSON at 64 KiB, and validated checkpoint content at 128 KiB. Native action generation is not evidence of a delivered wake. The v5 runtime's explicit host-injected dispatchCodexWake supports only scope harness codex and privately bound desktop thread/host targets. Trusted native read/send callbacks are required; injection does not prove authority or grants. It requires exact idle preflight by default. A host may explicitly opt into allowColdWake:true for exact native notLoaded evidence after verifying its existing sender can load the enrolled target; this is not idle or event-ingress proof. Busy/error/unknown evidence still holds delivery. It commits a SQLite claim before sending once, and retains claimed/uncertain attempts without automatic retry. Each callback has a bounded observation timeout, not cancellation. Acceptance is not receiver acknowledgment or work completion; synthetic tests are not live acceptance. See the Codex dispatcher contract. The v5 listener's opt-in dispatch-claude command resumes a privately bound claude-code target {kind:"claude-code",sessionId:UUID,cwd:ABS} using a trusted absolute operator-supplied executable; pass the prepared action's .arguments on stdin. It fixes flags requesting full model ID claude-haiku-4-5-20251001 and a $0.25 provider budget, with safe-mode/tool-free/strict-empty-MCP flags. It claims before spawning and bounds runtime/output. Exact argv does not guarantee the served model or provider billing: inspect actual assistant-model telemetry, not auxiliary modelUsage. The served model may differ from the requested model ID; sub-budget success does not prove a hard spend ceiling. Only exact native success is accepted, never acknowledgment or lifecycle proof. Claimed/uncertain invocations never retry automatically; reconcile exact receipts after confirming the old process is no longer executing. The same-session fence covers one local journal/scope, not other processes/journals/scopes. Keep native routes and CWDs private; do not sign in, create sessions, change credentials or force takeover as dispatch setup. Synthetic fixture success is not authenticated native acceptance. See the dispatcher contract. coord-v5 handoff verification import --config ABS --db ABS --receipt ABS retains a private, scope-bound operator attestation through restart. The receipt envelope is {schema:"handoff-verification/1",principal_id,workspace_id, workstream_id,stream_id,package,verification}; package bytes bind the offer digest and exact access-requirement set, and referenced ready/offer/publication events must already be in the authenticated local journal. Views consume valid retained checks automatically, fail unavailable on tampering, and refuse expired pending readiness. A historically accepted owner is not revoked merely because checks expire later: with multiple ready events, preserve only proofs in the replay-accepted transfer's causal history. Identical authenticated source copies count once for receipt bindings; differing event content under one ID fails closed. Import does not independently verify remote artifact bytes, remote permissions, native wakes, or source completeness; do not describe it as a verifier adapter or use partial coverage to claim all-clear or takeover. Current proof validity is its own fact, never merged into handoff state. Every handoff row carries verification: {state:"valid"|"expired"|"absent"|"unknown",valid_until, ready_event_id}. An accepted row binds this fact to the exact ready event named by its accepted event, which may differ from the first retained ready displayed on the row. Causal acceptance and proof validity are orthogonal: a clock must never un-accept a causal event, so an accepted handoff whose checks lapsed keeps state:"accepted", unchanged ownership and no recheck diagnostic, while reporting verification.state:"expired". Pure replay defaults the verification clock to asOf; an explicitly malformed verificationAsOf yields unknown while preserving causal state and ownership. Replay returns early without an asOf, so no row claims validity without a causal clock. absent means no retained receipt resolved and only occurs before readiness.

2.0.0 ships the truthfulness spine only: typed command outcomes, exit status that agrees with the body, deterministic identity precedence, and distinct empty, tombstoned, unreadable, and unknown states. Those direct canonical-read paths are the required fleet-adoption target.

Generation-backed public serving is dormant in 2.0.0. Do not run or require the cancelled epsilon measurement, set public_read_epsilon_verified, treat a current generation as public authority, or infer that authority from the release version. Cursor schema 2 remains a separate activation that requires its own fleet version fence and proven CAS transport.

The 2.0.0 tag set FulcraFileTransport.public_read_v2_enabled to true, so migrated folds entered the unverified generation wrapper and returned UNKNOWN before their canonical handlers ran. 2.0.1 and later set it to false, making dormant serving real; adopt a later release, never 2.0.0. This is a source fact, not evidence of which build any live host runs.

Fleet adoption is functional, not epsilon-based. Every live host within the recorded SLA must run the exact released build (with named, evidenced exclusions), and at least two credentialed hosts must verify queue, needs-me, review, forge, roles, presence, and reconcile through the direct canonical paths. Any required UNKNOWN, degraded fallback, or nonzero result blocks the adoption claim. Release, adoption, generation serving, and cursor-v2 activation are four separate facts; never use one as evidence for another.

Working tree

Prefer a per-agent git worktree, not a shared checkout — concurrent sessions sharing one working tree clobber each other's index/HEAD (interleaved commits, orphaned merge conflicts). Each session gets its own tree (and its own per-cwd identity): git worktree add ../<repo>-<purpose> -b <vendor>/<purpose> origin/main. Conflict markers or staged files you didn't create mean you're sharing a checkout — move out before committing.

A worktree does NOT isolate the stash stack. Stashes live in the shared .git, so git stash in your own worktree reaches into the same stack every other session uses. A git stash push with a pathspec that matches nothing succeeds silently and stashes NOTHING — and the git stash pop you pair it with then pops somebody else's entry into your tree, as a conflict you did not cause. If that happens: git checkout HEAD -- <their paths> to restore, and CHECK git stash list afterwards to confirm their entry survived. Prefer a scratch commit on your own branch over git stash entirely.

Commits

End the commit message with the trailer Co-Authored-By: <your model> <user@example.com> (e.g. Co-Authored-By: Claude Opus 4.8 (1M context) <user@example.com>).

Credential custody (bot tokens)

Where a team runs a machine (bot) forge account, its credential custody is team-store material, not repo material. The generic doctrine:

  • A bot PAT is read at runtime from a secret store, never embedded — never in an OS scheduler plist (plaintext at rest) and never in argv (visible in ps and shell history).
  • Rotation is stage → verify → promote: verify the candidate under a staging name before overwriting the incumbent — a piped empty value can wipe a keychain entry silently and still exit 0, so always paste at the interactive prompt — and rotate EVERY home the credential lives in BEFORE revoking the old token.
  • Agents cannot mint tokens — an expiring token needs an armed operator reminder on the team bus. Never let a token value reach argv, stdout, shell history, a repo file, a scheduler plist, a log, or a chat transcript.

Documentation rules (standing, operator-set)

Public documentation uses synthetic identities, account IDs, host names, and data. Keep personal content, team rosters, live measurements, deployment incident records, and private approval history in the team's own storage. Examples must let a new user configure their own team and recipients without inheriting a live account.

Write installation and plugin setup for the person using the tool, including someone who has never opened Terminal. Agent and contributor guides can assume their stated technical context. In both cases, readers should be able to follow the instructions without knowing the maintainer's machine or account.

Standing rules:

  • Truth over aspiration. Document live, verified behavior; stamp verification dates and drift headers where the platform moves faster than the repo (the FULCRA-PRIMITIVES pattern). Doc claims get adversarially reviewed like code.
  • Exact commands, exact paths, canonical form. Bare coord-engine, never uv tool run coord-engine (not on PyPI). One wrong documented filename made role-gated reviews structurally unapprovable (v1.6.4 fix) — path precision is correctness, not style.
  • No dead or broken references (operator rule, 2026-07-14): relative links must resolve, referenced files/commands/sections must exist, and mentions of real repo things should BE links. Sweep on every docs QA pass.
  • Teach fail-loud, never fail-quiet. No documented pattern may swallow errors; if a leg degrades to a no-op without its backend, the doc says so in bold (the silent-writer darkness).
  • Docs ship with the change, same PR, dual-green. Docs debt is in scope, never a follow-up. This file is the ship-gate.
  • One canonical home per fact; everything else links to it. Scattered version pins and duplicated doctrine are drift bombs.
  • Historical docs (proposals/, superseded designs) carry a historical banner instead of being rewritten; broken references get fixed even there.

Writing for upstream (issues & PRs to fulcradynamics/*)

Findings go to Linear, never to GitHub issues (operator rule, 2026-10-01). File findings as Linear tickets on the appropriate board (Platform/PLAT unless clearly another team). Never open GitHub issues on fulcradynamics repos. Why: the engineers triage in Linear, and an issue opened on a product repository lands outside their queue and has to be migrated by hand (fulcra-api-python issue 115 was, on the day this rule was written). This covers every agent and courier on the fleet, whatever account it files under. Pull requests upstream are still allowed where a session has the access; the writing rules below apply to those and to the Linear ticket text.

Upstream reports must be understandable without reading this repository.

  • Succinct. First sentence states the bug. Repro, expected, actual, one self-contained piece of evidence (a curl, a traceback). Ten lines.
  • Their vocabulary only. No fulcra-tools terms, codenames, or links — evidence must reproduce from their code alone.
  • Everything else — discovery story, fleet impact, workarounds — stays here.
  • Filed by a courier, and it says so. Most sessions cannot reach repos outside the one they were launched against, so upstream work is filed by a session that can — which means the only identity upstream sees belongs to the carrier, not the author. Close that with the last lines of every upstream PR or issue body, above the Claude Code footer:

    Filed by `<courier>` on behalf of `<originator>` — automated agents operating
    on one maintainer's account. Replies reach the originator.

    One name and no "on behalf of" when they are the same agent. Attribution here is ROUTING, not credit: it tells upstream who can answer and tells us whose work is in that thread. Identities only — no internal paths, task ids, or topology; the rule above still applies to this line.

  • Name the access level before promising delivery. Report what the API says — pull/push/maintain/admin — and which of file, merge, approve-CI it permits. Filing from a fork needs read; merging needs write. "I have access" is not an answer.

CI and workspace membership

  • macOS CI is path-filtered and bills at 10×, so it only runs on changes under packages/**, skills/fulcra-agent-automation/**, the workflow file itself, and the dependency manifests (pyproject.toml, uv.lock) — see .github/workflows/macos.yml; test_ci_trigger_coverage.py fails if trigger and coverage drift apart. Everything on Linux (uv-workspace.yml) runs on every push/PR to main. Both gates retain their full selections and report interpreter/cwd/module paths, test nodes and slow setup/call/teardown phases. Their finite job bounds and completed-run evidence live in the workflows. These measurements do not guarantee future runtimes. A timeout is an incomplete run, never a passing gate; investigate it before changing coverage or the bound. The upshot: for anything outside the macOS trigger set (docs, most skills), the local run is the only pre-merge macOS check — run the relevant suite before you push.
  • Local verification. coord-engine is CI-gated on both runners, but still run its pytest suite locally before pushing.
  • Workspace exclude. Any directory under packages/* that is NOT a uv member (no pyproject.toml) must be added to [tool.uv.workspace] exclude in the root pyproject.toml, or it breaks uv sync/uv run/uv tool install for everyone (the uv-workspace CI guards this). packages/web-ui (a frontend, no pyproject.toml) is excluded for this reason.

Fulcra platform surface & records

Collect v1 migration (in progress, 2026-10-23). Actual v1 custom types are Event/<UUID> and Metric/<UUID>; an /ingest/v1 endpoint writing annotations is still a legacy datatype path. New opt-in shared builders/transport live in fulcra_common.v1, documented in the shared library README. The SDK floor is 0.1.54 (workspace lock 0.1.56). Validate served custom schemas, use explicit v1 destination IDs/version, preserve primary source identity and verify readback before claiming an import landed. Do not blindly retry an uncertain POST or silently fall back to legacy annotations. Caller migration is tracked by the implementation plan; do not claim all Collect/browser writers have switched yet. Unrelated coordination/prefs/vault streams are not implicitly converted through this shared library change. V1 destination creation uses the account-bound resolver and durable CreationJournal in data_types.py. Keep its private SQLite file across process/host changes: a pending creation with no response is reconciled by owned type/schema readback, never by repeating the POST because the next listing looks empty. New schema versions and destination changes require an explicit reconciled mapping. Base-only types omit the optional custom schema fragment (empty fragments are rejected by the live API). An explicit HTTP 422 permits a corrected specification, while an identical rejected request or an uncertain outcome is never automatically retried. Creation now captures a durable reservation nonce and retains a known full UUID from JSON or a same-origin 303 Location before later proof; never follow its alias redirect or substitute a different type after failed readback. Keep the format-1 journal’s binding provenance, reservations and receipt audit together; missing/conflicting evidence holds. Stop older writers before upgrading it. Legacy readonly inspection and writable migration rules live in the shared creation boundary and its receipt regressions. Owned custom-type resolution, exclusion discovery and the Collect picker use the shared direct input-service reader, including retired types. Do not replace it with aggregate catalog emptiness/uniqueness: that aggregate can silently omit backend failures. Exact endpoint, account proof, bounds and failure rules live in fulcra-common's v1 boundary. Collect-side v1 writers use CollectRecordSession for strict Collect-only auth, captured settings/epoch checks, request-time token rechecks and leased progress commits. PurpleAir is the first migrated family: its account/epoch-bound pending outbox is reconciled before fetching new samples, and exact v1 readback precedes receipts/cursors. Retain legacy state for historical mapping and both private state journals during host cutover. The reusable V1RecordOutbox retains immutable batches in the dedicated record_outboxes table until exact visibility. Schema v8 keeps this 16 MiB-per-batch store separate from 64 KiB cursor KV; workers bind outbox_get/outbox_set to the plugin namespace. Preserve pre-upgrade backups and subsequent pending payloads when rolling back to older binaries. Drain before fetching a new sample and never overwrite pending data. New shared and PurpleAir pending envelopes carry dispatch_version=1: an immutable scope/payload binding, exact issued source subset/body hash, and retained exact positive IDs. The source dispatch controller checkpoints prepared to issued through the actual before_submit seam after validation/serialization. An issued missing/partial payload is UNKNOWN, never permission for another source POST. Later exact visibility reconciles without resubmission. Existing newly prepared same-ID correction behavior is retained; issued/legacy mismatches cannot overwrite. Positive source evidence persists before native repair can erase it. An issued excluded ID without that evidence cannot complete from absence. Legacy envelopes are preserved without adoption; missing evidence holds, while exact allowed rows can reconcile without POST. The lease covers pending read through guarded clear, including checkpoints. Collect source delivery requires this durable controller; no direct untracked source ingestion is permitted. Native repair remains a separate durability gate. DB version9 is a protocol marker that makes restarted version8 binaries refuse the upgraded state. Stop every older daemon/worker before upgrade: a process with an existing cached DB connection is not retroactively fenced. Never roll an older app onto versioned pending state. A consistent pre-upgrade backup and subsequent original pending evidence are necessary for rollback, but restoring that backup can erase issued evidence and permit replay. Reconcile unresolved source effects and establish a safe writer disposition before any downgrade; never strip the marker or treat a backup alone as proof replay is safe. Batched v1 ID/source readers use bounded matcher groups inside one selector (binary vector OR is unsupported). Tag creation intents are shared by account/name across plugins in the same private journal; a lost receipt requires current-account lookup before recovery. A saturated source read is unknown coverage, not an empty/matching-complete result. All 16 bundled media plugins and the retained Spotify IFTTT backfill entrypoint now use the guarded v1 media runtime on this branch. All fourteen standalone media import routes listed in the package guide now use guarded v1 Events; the standalone webhook server now shares that authority. The vendored Netflix importer now uses the installed canonical console/script adapter with a versioned shared capability check before auth/source. Skill-folder-only copies support stdlib check-only; no PEP 723 live upload/install or annotation fallback remains. Its cli-netflix authority uses independent CLI auth, optional Event pin and the shared Watched spec/journal; account/profile/pin/spec changes hold pending. All original targets are proved before recovery, which precedes source access. Whole new input gets local/schema/current-primary conflict proof before serial <=500-record chunks; only the in-flight chunk is durable. Exact complete-group current counts remain separate from recovery/exclusions, and --no-verify is refused. Slim source IDs lack profile identity and cannot prove arbitrary overlap correspondence. Personal import finishes independently of optional legacy all-annotation sharing; native share propagation and historical conversion are UNKNOWN. See the Netflix agent guide. The released app has not switched. The guarded media runtime requires explicit v1 mappings for existing annotation selections, preserves user tags/provenance/declared enrichment on source corrections, and refuses primary identity collisions. Preview does not create destinations/tags or drain queues. Daemon media cursors live in account/epoch/raw-settings-scoped KV envelopes; legacy watermarks remain untouched and cannot prove v1 delivery. The private v1-media-twins.sqlite stores account/destination-scoped high-confidence record IDs, and each hint needs matching current-account record readback before an auto-discard skip. The old global JSON cache cannot authorize a v1 skip. Retain the new index during host cutover. Threaded webhook requests serialize on their shared writer/outbox; preview reports would_post, and only the outbox visibility commit emits a v1 receipt. The webhook proves its owned destination before listening, reports typed destination/verified/preview counts, and closes the server on loop exit. Its bearer credential is optional only for loopback binding. The daemon rereads configuration each tick and retires service workers on epoch/raw-settings revision changes; replacement waits for confirmed exit, with an owned-group forced stop after a 10-second monotonic grace checked on ticks. Unknown configuration/account transitions pause new scheduled work and retire services. Host cutover and real source QA gates remain. See the media contract and service policy. The standalone media configuration and adapter now route those fourteen commands through fixed cli-media profile-local authority with separate CLI/env authentication, never Collect sign-in fallback. Bootstrap atomically saves cli-media-v1.json; every retained legacy category needs an explicit Event/UUID mapping before metadata creation. Saved account proof precedes original pending recovery, which precedes configuration changes and migrated source resolution, discovery and parsing. Preserve creation receipts, pending evidence and legacy selections on every hold; reset is retired for every flag combination. Status is cached read-only inspection of v1, retained_legacy and pending, exposing retained payload size/digest only. UNKNOWN is never all clear. Detached preview cannot drain pending work or prove caught-up coverage. Standalone webhook routing now uses the owner described below; this intermediate source branch is not rollout. See the configuration tests and adapter tests. The five standalone v1 poll commands now select strict scans and private scoped cursors. The five daemon polls have a separate strict progress contract: fresh v2 scopes never adopt annotation or pre-strict v1 cursors, and final quiet credential checks precede a second authority guard and exact KV readback. Standalone recovery precedes bounded source-credential reads. Current verified delivery precedes cursor commit; configured caps, malformed skips and source changes withhold advancement. Both strict poll paths require HTTP 200 and refuse any Content-Range, multipart byte-range body or mismatched declared raw length at their shared source reader before parsing; duplicate/coalesced content types are ambiguous and refused too. A parseable partial response cannot authorize current delivery, cursor progress or history success; preserve the prior cursor and report failure. Legacy watermarks never seed v1 cursors. Public envelopes append a closed cursor state/reason or null; withheld success is not caught-up proof. The observed import progress seam lets all fourteen migrated CLI routes retain known counts after cleanup. It is a last serialized invocation's lower-bound snapshot, never a receipt or authority; shared concurrent handlers cannot use it for caller attribution. A helper test is not evidence that a route or installed app switched. The standalone CSV contract now uses explicit owned full Event/Metric targets, strict CLI parsing and a dedicated cli-csv namespace. Recover original pending rows before opening new input; preview is local and does not recover. Preserve primary-source identity and compatible cloud enrichment; Metric units are exact destination metadata. Bootstrap's same-name durable intent cannot be bypassed by changing parameters. Known complete-group progress survives later failures; UNKNOWN is not empty. Legacy export/admin remain separate, and old client record methods refuse before auth. Pure parser/media consumers retain defaults. The CSV skill describes setup/recovery probes; helper tests do not establish installed rollout. The labs importer now uses actual v1 Metric records through dedicated cli-labs authority, with existing clinical validation and source hashes unchanged. Selected retained legacy markers require explicit --marker-target MARKER=Metric/UUID pins. Recover original pending before new JSON/PDF access; prove all actual pending targets from private exact marker/spec witnesses, then retain per-group kernel recovery validation. Whole new batches get full schema and existing-primary conflict proof before staging. Optional record unit is omitted; exact immutable Metric metadata owns canonical unit, while nullable raw_unit preserves source spelling. Counts are complete-group lower bounds; current completed evidence and recovery remain separate, and unsupported marker attribution is UNKNOWN. Cached status is local evidence, never remote series counts. Original legacy cache/PDFs remain; old write seams refuse. The labs skill teaches stateful recovery and unchanged two-pass/operator-review gates. Source tests do not prove installed app acceptance, real reports or historical conversion. The standalone webhook contract uses fulcra-media webhook --port 8766 --json, preserving default 8765 and explicit selection without fallback. Startup recovers pending work and prepares all three categories before bind. One private thread opens, uses and closes CLI authority; profile leases last through cleanup. HTTP handlers submit defensive snapshots and receive their own settled results. Closing rejects new jobs, drains accepted work and joins cleanup; late parsers cannot access released authority. Health is cached liveness, not fresh ownership proof. Ready follows signal installation and the real-loop health handshake; successful shutdown follows cleanup. These actual synthetic HTTP/lifecycle tests do not establish an installed receiver or sender reachability. Keep the daemon's service lifecycle separate. The unbound media writer retirement removes the obsolete annotation/wrapped/typed pipeline and orphan CLI helper. Four public writer seams refuse before auth/input/empty/cache/preview effects; construction, read/admin and tag compatibility remain. Keep the captured Collect bridge and native namespace classification; do not restore legacy record fallback. The standalone Trakt policy contract uses read-only prompt inspection and immutable exact offered pairs intersected with fresh shared proof. Existing hints require owned readback/exclusions; excluded current-input highs cannot justify skips. Choices never mutate saved authority. Explicit ask is rejected in JSON/non-TTY before source; omitted twins keep and warn only for candidates there. Post-cluster totals include policy skips; Trakt has no cursor. Default None preserves Collect config/default precedence. The actual Trakt CLI and ordinary Keychain-backed daemon worker now require a complete bounded source scan before current-input delivery. All four pagination headers, effective clamped limit, exact page cardinality and unique integer history IDs must agree; missing evidence fails instead of implying one page or empty history. One private cooperative budget spans auth and the single keychain 401 restart, with rotated tokens persisted before a late deadline refusal. Other five poll interfaces and Trakt source IDs/normalization/cluster/twin policies remain. Original pending recovery may already precede a failed current source. This proves self-consistent returned pagination, not an immutable account snapshot. The Trakt source owner adds exact local credential/consent generations, one shared OS-user consumed-grant journal and recoverable secret receipts. Ordinary workers never implicitly select the legacy CLI file on missing/partial/UNKNOWN/disconnected Keychain state; a direct wrapped-plugin file fixture is not worker selection proof. Preserve the source journal/receipt lineage across profiles and never remove claims to retry. Manual pair edits credit only verified exact supplied values, not failed intent; refresh/recovery binds only its own exact consent-preserving successor. Explicit Keychain authorization runs outside short control locks; bounded quiet mutation then rechecks its still-current edit/profile. Stale OAuth results cannot overwrite newer setup. The wrapper registers current source guards only after original recovery and retains them through final cursor handling, with local-only checks at nested mutation boundaries. Background Trakt receipt/mirror writes use the quiet child, not generic interactive setters. The current provider-identity contract adds exact selected-credential probes before/after history and a terminal proof before normalization, policy, writes and progress. A selection-keyed durable pin survives credential/profile changes; a mismatch stays held without automatic reset. Source journal version 2 preserves valid v1 entries on upgrade; older v1 readers fail closed. Fence older participating writers before upgrade and preserve the whole journal/receipts. First pinning gives no historical attribution. Installed/ signed access, live-provider acceptance and old-writer/copied-grant retirement across hosts remain gates. No hard interruption of an in-flight grant is promised. Migrated producers expose Plugin.record_data_types(settings) and destination steps name SetupStep.record_slot (single-slot producers may omit it). Their authenticated setup uses the owned v1 catalog/schema and saves full IDs in v1_destination_ids; legacy annotation binding routes reject these producers. Rebinding checks pending uploads both before resolution and under the account/ settings commit fence, rotates the source epoch and retains old annotation state. A producer with a custom pending format must provide Plugin.record_pending; otherwise setup checks the shared v1_pending_records outbox. Raw saved-settings fingerprints fence pending batches even across manual TOML edits. The picker shows one latest entry within 30 days, not complete history. See the setup contract. Same-account silent token refresh is accepted with request-time auth replacement; account/epoch changes cancel work and cross-origin redirects are rejected. See its delivery contract. RunContext.fulcra_token() is now a compatibility alias for Collect-only collect_token(), including file-producing plugins: neither adopts environment or default CLI credentials. Silent renewal checks the existing/candidate/final keychain principal and fresh expiry, holds an account-shared lease through its final write and yields to a newer interactive sign-in. Missing identity or a durable account-transition gate cannot be repaired by automatic CLI sign-in. 401 retries pass their original request token to prevent an old operation from retrying under a newly selected account. Gmail/Reminders/Todoist reject missing Collect auth before source/writer construction. The auth contract is shared by these plugin paths; standalone CLI authentication remains separate.

FULCRA-PRIMITIVES.md is the field guide to the whole platform surface (auth, files, annotations, queries, MCP), organized by agent capability tier — CLI/lib, raw HTTP, or MCP-only. Read it before re-researching anything about the platform, and check the installed fulcra-api version, not the repo (the CLI ships ahead of its git main on PyPI).

  • Spec-backed raw endpoints are first-class. Anything in the published Fulcra OpenAPI (api.fulcradynamics.com) is fair game when it makes the work easier — a documented raw REST call is a legitimate tool, not a last resort. Still prefer the fulcra CLI / Python lib when you have a shell and a verb exists; the MCP server is read-only.
  • Records have CLI verbs as of 0.1.37 (2026-07-15) — fulcra record DATA_TYPE [VALUE] and fulcra delete DATA_TYPE [RECORD_ID], both with -f/--file and JSON/JSONL on stdin for batch; fulcra catalog --recordable-only lists the types they accept, and the lib gained record_data_type/validate_records. Use them when you have a shell rather than hand-rolling ingest POSTs. The raw ingest endpoints (POST /ingest/v1/record/{data_type}, typed and preferred; the wrapped DataRecordV1 legacy path; the unpublished /batch) are still first-class when you need them — the primitives doc covers all three and the custom-type sources caveat.
  • delete is a tombstone, not an erasure — the CLI implements it by recording a DeletedRecord through the same ingest path, and there is no record-delete lib method. There is no hard delete and no dedicated update/replace verb. True-v1 Event same-ID timestamp/content updates, Metric same-ID value updates, Event/Metric deletion visibility and Event post-delete replay revival were separately verified 2026-10-23: see the mutation contract. Replays can revive deleted records, and native tombstones are not queryable; keep an independent durable disposition/audit and check it before replay. The shared V1DataClient requires explicit canonical record UUIDs and offers native delete_records with a durably captured action UUID; its receipt is submission evidence only. Prove replay exclusions and target absence before claiming deletion. Media copied- record source aliases count as existing data; opaque source IDs alone do not prove a different-importer fingerprint twin. RecordExclusions adds an opt-in owned Event policy keyed by full target type/UUID. It verifies policy visibility, retains a visible prior exclusion and fails closed on malformed/unknown reads. No restore or cross-host write lock is implied; callers keep durable action audits and check policy before/after source writes. Media/PurpleAir now check this policy before duplicate shortcuts and around queued writes on the development branch. Observed revivals need native deletion and absence proof before progress; excluded rows never count as posted/verified or seed media twin hints. Media chunk planning through delivery shares the local per-account record lease across processes and threads. Browser hosts are outside that lock; historical replay floors, controlled cutoff, other writers and durable Undo actions remain rollout gates. The catalog does not retain our datatype creation metadata key/schema fragment. Preserve the private account/key creation journal through host migration; unbound control lookup discovers owned served schemas (64 candidates/10s scan, up to 8s per schema HTTP request). A missing bound control, unknown schema or ambiguous match fails closed. Setup proves/binds the control before saving a source destination; previews cannot create or repair control state. ActionJournal adds opt-in private, immutable interactive intents plus transition evidence. Global action IDs cannot be reassigned to another account/epoch/request; submitted is not verified. Account-only old-epoch inspection and bounded, filter-bound recovery pages grant no mutation authority; unfiltered reads fail on unknown statuses. QuickRecordActor captures dispatch intent after schema validation, never resubmits an uncertain create, and requires a verified original for a new native Undo action with permanent exclusion and absence proof. An uncertain original remains submitted. Shared v1 record/native-tombstone POSTs reject redirects to prevent automatic body resubmission after a 307/308 response. QuickRecordSession registers a separate interactive epoch and requires the captured account/epoch without enabling a plugin. Registered contexts use shared leases; initial registration releases SH before acquiring EX and re-proves identity. Generic setup ingestion stays gated. The opt-in quick_record_v2 daemon envelope and authenticated /api/quick-record/v2 expose the protocol2 contract: captured scope/action identity, owned per-track Event bindings, account-scoped revisioned pin diffs, durable first timer stops, native Undo, paginated action / timer discovery, and snapshot-based stop reconciliation after a crash. Receipt failures under valid authority return saved pending metadata, not auth refresh. Legacy favorites remain unadopted and untouched, including during legacy definition metadata deletion. Preserve scoped pins and v1 destination bindings too; definition management is separate from native record Undo. The native client workflow captures immutable bounded requests before socket IO in a separate private client journal. Timeout/restart retries keep the original body and scope; response proofs must match the original action/timer and first stop time. One global timer-to-stop binding preserves the first local stop across later clicks; pending replies cannot change an observed record ID or datatype. Protocol2 socket replies are bounded at 8 MiB; requests and legacy replies stay at 64 KiB. Development native popover/preferences and web favorites now use protocol2 by default and are included in the published 0.1.5 beta. Complete packaged interactive acceptance and explicit old-epoch recovery remain separate. Unversioned commands/old authenticated HTTP routes return refresh-required before Collect auth or effects; their legacy serializers/sentinel Undo are removed. Native checks validate saved/observed action and timer proofs; local saved intents reuse their exact request. Bounded pending-action pages discover work beyond recent 20, including old-epoch rows that grant no replay authority. Drafts survive rerenders within their account/epoch/choice/timer scope; only a durably captured row clears. Busy refresh invalidates queued stale-account results and schedules a new handshake. Pin edits are additive CAS diffs from one complete scoped choice/revision view; logical/scope failures never count as success. Cached Preferences refreshes on reopen and Annotations selection, with deferred fresh reads after busy loads. Hidden and legacy pins stay intact. Client schema1 fails on incomplete/unversioned/future state instead of healing empty. New GUI imports stay lazy. The refresh host uses a Python AppKit subclass because plain NSView cannot carry its callback. Dynamic native rows must call detach_view before removal, releasing only our targets so retained callbacks/snapshots do not grow per rerender. Explicit old-epoch reauthorization and packaged QA remain release gates. Tag names are limited to 30 characters on creation. Collect reuses saved owned tag UUIDs through renames; new long/slashed or dot-segment source labels get stable short tag names without shortening record enrichment. Unknown creation remains fenced. Media validates raw declared fields before notes/metadata, reuses a codec validator, and compares UTC instants for durations, order, windows and receipts across DST changes. Full media nullable/nested/Unicode/multiple-tag parity and same-ID Metric timestamp updates are live-verified; see the mutation evidence. snapshot_json rejects non-string object keys at every depth, invalid Unicode and non-finite values before v1 metadata, action/outbox storage or transport. Do not rely on a bare JSON round-trip: Python can stringify nested keys and silently merge them. Valid zero/false/null values and Unicode content remain unchanged.
  • Projection is the sole timeline-annotation writer. Use the heartbeat projection fold (coord-engine annotate resolution <team> transitions). Its deterministic ids converge because typed ingest upserts matching explicit ids (live-verified 2026-07-14). The retired first-generation writer minted different ids and was removed after causing duplicate-record proliferation.

Attention v1 contract (development)

Attention's opt-in v1 contract and encoders have shared Python/TypeScript/Swift synthetic vectors; installed/default browser senders still use legacy transport. Preserve the existing v3 primary source and use the common UUID5 full-destination mapping. New URL inputs are already-scrubbed JS capture keys within the linked shared boundary; hold unsupported inputs instead of applying a second native URL normalization. New capture payloads retain milliseconds; history retains its stored precision. Reject malformed or nonzero submillisecond bounds, not silent rounding. The schema permits historical null device identity, but new contexts require an installation slug. The initial owned spec fingerprint is pinned; semantic changes need a new version. Pure codec checks grant no account/destination/replay authority. Complete the linked owned-resolver, immutable-queue, readback/exclusion, native-protocol, active-visit and installed-state transition gates before changing default browser writers.

Attention's opt-in browser journal uses IndexedDB compare-and-set for account/generation transitions and publishes Event creation intents durably before a future POST. Unknown creation remains pending across restart; never reset it to create again. Reconcile the original intent under fresh same-account authority. Journal state is not API-principal proof or upload permission. Existing auth/default senders are not wired to it; actual browser persistence and Safari sharing remain rollout gates.

Its IndexedDB v2 upgrade retains the v1 gate, generation history and Event intents, and adds account/label tag intents with unique account/create-name reservation. Tag resolution uses the same bounded alias naming as Python, records intent before POST and explicitly refuses . and .. labels before lookup path normalization. It records a returned UUID as submitted before name readback. A submitted UUID cannot be substituted; an unknown attempt never authorizes another create. Only a target lookup's positive 404 permits creation: identity-endpoint failures carry a separate HTTP error code. Resolved tag UUIDs survive cloud renames as historical ownership bindings, not live-tag or upload proof. Name collisions, unreadable state, unsupported strict durability and full journals refuse; never evict pending work. Defaults remain unchanged. See the synthetic migration/race tests.

The opt-in v1 HTTP boundary captures one account/generation and request JSON before awaiting. A fresh token's candidate UUID must agree with that gate AND /user/v1alpha1/info; JWT/display claims alone cannot authorize a request. Every provider/body await is followed by current token/gate checks; a late result cannot acknowledge a changed scope. Same-account token renewal is allowed, while this helper performs no credential writes or refresh. Its caller must publish generation changes before changing capture account. Only allowlisted production routes, no redirects/cookies, bounded fetch/body waits (abort timer plus absolute monotonic checks) and finite Unicode JSON are accepted; mutations are never blindly retried. Disabled capture cannot ingest. Browser fetch supplies DECODED bytes: its retained-body cap is not a raw-wire/decompression bound. This transport grants no schema/creation/queue/exclusion proof and is not called by default senders yet. Keep account/schema/durable-delivery rollout gates. The opt-in browser owned-type inventory uses the direct caller-owned input endpoint and rejects a partial, redirected, paged or malformed whole list. Identity/proof fetches request no browser cache; wrong-scope 404s cannot become tag-creation permission. Frozen inventory entries are not schema proof or destination bindings. The shared authority contract and browser tests describe the bounds; actual browser auth/CORS/upgrade gates stay open. The pure Attention schema proof requires the closed supported Event/Attention schema family, rejecting unknown assertions/references instead of assuming a matching field subset is sufficient. It freezes the parsed schema before hashing and retains the exact serialized text whose UTF-8 digest is checked. Keep that text with its digest; do not call it raw-wire proof or assume arbitrary JSON serializers reproduce it. The development contract defines supported shapes/bounds. This pure check grants no owned binding or upload authority; defaults remain unchanged. The opt-in Attention destination binder requires fresh direct ownership, BOTH authoritative input/served-schema proof, and a final unchanged-input/active-type check before its journal commit. It is explicit setup with local effects, not a preview. Keep transport and effects on the identical journal handle per operation. Pins survive renames; unknown type creation never authorizes another POST, and known returned UUIDs persist as submitted before further network work. Older binaries that cannot read that state must hold it, never clear it. Exact proof/known immutable base-transform handling and tests live in the development contract. No default UI/sender, capture, queue or exclusion authority is enabled by it.

The Attention binder also exposes verifyAttentionV1: read-only fresh proof of an already resolved original local destination. It checks complete owned input, closed input/served schemas, unchanged final input, then the exact original reservation generation via requireCreation; missing/submitted/pending or changed intent never heals. Verification returns the original reservation generation; setup's existing result shape stays compatible with queued captures. First binding still requires a unique canonical candidate: a submitted UUID receipt alone does not disambiguate siblings, while explicit/prior-resolved pins retain rename semantics. Setup and verification share one <=10s monotonic/timer budget, <=8s/remaining HTTP reads and a terminal cancellation flag. Setup passes an AbortSignal through creation transactions: check resumed callbacks and abort an active uncommitted transaction on cancellation; detach listeners on settlement. A verified receipt already returned by HTTP may still be retained historically after outer expiry/account change. A response rejected inside HTTP remains UNKNOWN; do not claim its UUID was retained. The binder tests cover ambiguity, readonly tuples, same-account gate rotation, cancellation after actual add/put and returned-receipt retention. This grants no delivery authority.

The opt-in Attention outbox is local pending capture only. Its IndexedDB v3 upgrade retains v1/v2 stores. Capture freezes account/generation, full destination/specification, both schema texts/digests, installation, original event, primary, flat record/tags and exact serialized payload before strict commit. The transaction requires the enabled current gate and resolved local datatype/tag bindings; every read reproves the stored envelope and rechecks the gate after hashing. Same identity with different content or generation is held, never overwritten or implicitly rebound. The 5,000-entry/32 MiB aggregate envelope limit and quota failures reject without eviction. No POST/settlement/deletion API, legacy adoption, active-visit checkpoint or default wiring is supplied. Digests are local integrity/reproduction evidence, not provider receipts. Bounds and synthetic queue tests live with the development contract; actual browser persistence, quota, upgrade and Safari sharing remain gates.

The network-free browser mutation journal adds atomic IndexedDB v4 ownership for one pending logical operation per account. Upgrade preserves v1/v2/v3 data and rejects malformed old structures. Retain both history and the terminal current pointer: their count/byte frontier detects lost metadata; expiry never releases uncertain work. Current/requested rows receive digest reproof; older unrequested history is covered by count/frontier checks, not a fresh content audit. Request hashes bind original account, generation, action, operation and exact request bytes. Prepared/issued work cannot move to a new consent generation. Issue is a single-winner CAS; reopening an issued intent grants no second issue. Verification stores immutable caller evidence, not independently checked remote truth. It cannot authorize HTTP, native deletion or queue removal. Future actors need issued-once phases for each physical effect under continuous ownership and exact, atomically bound queue settlement. Legacy requests and all proofs are limited to64 KiB; phased request limits are described below. History permits100,000 total actions and32 MiB retained request/proof bytes per account, with proof headroom reserved beforehand. Capacity/quota failures preserve all work; there is no eviction/reset/release API. Ownership tests cover upgrades, corruption, deadlines, races and restart. The development contract records the remaining actor, native browser and default rollout gates.

The same journal now uses an IndexedDB v5 version fence while preserving existing v4 payload rows/pointers byte for byte. Legacy intent format1 stays network-free and cannot acquire phases implicitly. New closed format2 captures a fixed complete manifest before reservation: deliver then repair, or policy then delete. Old manifest1 retains its64 KiB cap; manifest2 bounds and references are described below. Inline JSONL has at most32 records per body. Phase CAS has one issue winner; prior phases must be proven before later phases advance. Immutable phase caller-proof hashes bind original request, role/index and body. Separate final logical proof retains the owner until every phase is verified. Reserve headroom for both phase proofs plus final proof, count actual bytes once, and deep-detach/freeze nested states. Explicit preexisting/not-needed evidence avoids inventing a dispatch. This is storage only: phase plans receive finite JSON/route shape checks, not served-schema, policy or provider validation. A typed HTTP transport itself wins issueGuardedEffect immediately before its one fetch, categorically refuses legacy rows, and holds uncertain POSTs without reissue. Phase tests cover legacy byte preservation, phase order, corruption, asynchronous input races, capacity headroom, quota and deadlines. No sender/default/queue removal follows. All mutation APIs accept optional cancellation after the absolute deadline; active uncommitted writes abort, while a committed issued phase never resets. The guarded CAS requires exact original resolved creation/tag tuples retained before reservation in details.dispatchAuthority, then rechecks those tuples inside the same strict gate/owner/history/body transaction. A fresh replacement cannot substitute for original authority. Exact code-unit sorting preserves Unicode labels and allows property/array reordering. Original reservation generations can predate the action. Legacy guardless requests refuse guarded issue; plain issueEffect is storage-only compatibility and forbidden to HTTP actors. verifyGuardedEffect similarly checks the exact original tuples in the same transaction before phase-proof publication or reuse, and requires the original nonterminal logical owner still held. Terminal old actions refuse guarded reuse; plain verifyEffect remains storage-only historical compatibility. See the proof tests. These remain caller evidence and local predicates, never provider truth or queue settlement. Typed submission adds fresh schema/type/tag proof; replay policy and sufficient action guards remain actor duties. The64 KiB details cap can hold large guard sets even when the queued record fits; full admitted-row delivery coverage remains a rollout gate. See the dispatch tests.

The opt-in action actor reconciles only an original retained delivery/exclusion intent. Fresh owned target/control/tag/native-schema checks bracket exact source and canonical policy reads, including zero-POST reuse. Closed immutable phase evidence binds original account/generation/action/body/authority and schema hashes. Issued source absence stays UNKNOWN without another application submission; a later policy permits prepared repair only after positive original source evidence. A consumed not-needed repair cannot become a deletion, and native revival holds. Results are frozen as-of-read observations: success retains the owner and queue; UNKNOWN asserts no current ownership. Default integration is still pending. V1Http.withReadCancellation preserves the original transport configuration and all inherited cancellation signals for nested reads. The actor has one 30-second maximum budget; repeated authority GETs can exhaust it on a slow service and need real-service acceptance before rollout. One guarded CAS/application fetch is not a one-wire-attempt guarantee: isolated Chrome repeated an HTTP POST after an empty response without a second application fetch. Never infer backend job quiescence from the local phase, receipt or an absence read. See the actor tests.

The opt-in decision authority contract now shares one closed target/control/schema/tag/native inventory pair per snapshot, with fresh A → exact policy/source → fresh B observations. Opaque capabilities remain bound to the exact journal/HTTP root, bearer, original request/dispatch and cancellation/deadline. Public helpers stay independently safe. Standalone callers must publish a new gate generation before every bearer replacement. The source-only Chrome worker auth owner adds a bounded same-account renewal exception with exact predecessor/successor, retained response, fresh API principal proof and exclusive owned lifetimes. Unannounced token-only replacement remains unsupported. In v1-held both drains stay disabled; versioned worker commands own settings/auth, with noncredential settings atomically stored in broker IndexedDB. Read-only page settings commands wait for local worker initialization without online recovery or direct page authority creation; controls wait for settings and surface failed reads as held. The canonical contract also requires the separate once-only initialization witness: missing database/witness stays UNKNOWN, without reimport/reset. Local revocation/display cannot wait on online recovery. Pause retains selected auth with action admission closed; resume uses fresh consent/generation and sign-out clears selection. Legacy state stays original evidence. Source-only held capture ingress retains actual visits/backfill with strict atomic serialized-row accounting and no eviction. Null positive descriptors keep actual input unattributed; durable local evidence is never an uploaded count. Preserve category privacy, original scrubbed keys, restart/scope gaps and legacy old/new observations; missing input or unreadable accounting stays UNKNOWN. Completed setup publication, actual draining, installed sender fencing and Safari native integration remain gates. The guarded issue CAS stays the last authority await before application fetch; no cached proof bypasses journal predicates. Actual isolated synthetic Chrome checks are separate from provider latency, installed auth and default activation.

The source-only explicit browser protection command installs the concrete fixed DNR policy only on null-payload protection-setup under an already admitted worker-owned lease. Do not install on boot, start online admission or supply a protector/ready flag from a page. Preserve original state/credential/gate and lifetime checks, including a synchronous cancellation check immediately before native update. A timed-out/revoked native promise retains its installer reservation until actual settlement; effects remain UNKNOWN and must not trigger compensating cleanup. Its as-of-read result leaves capture and drains held. Task 4 permits source preparation; actual native procedure, original C0/browser obligations, real account/destination and Safari gates remain separate.

The inert browser candidate presentation adapter can display bounded, strictly shaped full Event ID/name candidates through the Wizard's versioned page seam. Account matching is presentation scoping only. The actual worker still reports SETUP_HELD; no protected production listing, selection/setup write, descriptor publication or drain activation is added. Candidates have no default choice and late/unmounted results are discarded. Preserve Task 4/C0/native sequencing, installed evidence and Safari gates; synthetic message/Chrome/IndexedDB tests do not certify production listing. Shared Chrome test setup denies global fetch before imports and each case, reestablishing it after global restoration while permitting later synthetic fixture overrides. This is a JavaScript fetch-seam guard, not an OS/socket/native-browser sandbox; follow the linked fixture-reset limits. Candidate labels, IDs and raw response errors must not enter logs.

The unused bounded local evidence APIs keep read cancellation separate from writer completion and use noncreating exact-version handles with shared monotonic/record/byte budgets. Raw capture records and original owner snapshots grant no setup, origin or action authority. Preserve private credentials, full original-input validation and strict writer predicates; native QA and later activation remain gates.

settleV1Action adds opt-in atomic settlement with one maximum30-second budget from history through actual actor and local commit. A private observation capability binds fresh evidence to the exact journal and original budget. Its strict transaction rechecks original authority/generations/history/phase proofs and exact referenced queue bytes, then commits terminal receipt/pointer and removes only that original row together. Inline exclusion performs zero queue writes; inline delivery holds. Historical receipt lookup precedes body/provider access: already-settled leaves newer owners/requeued same-ID rows untouched and asserts no current provider freshness. Lost completion is UNKNOWN with localCommit: unknown, not a promise all local data remains. Precommit aborts roll back; confirmed commit survives late cancellation. See the settlement tests. Default draining, bounded terminal archival and installed-browser acceptance remain gates. Chrome npm test/watch use two workers to prevent measured host oversubscription from exhausting operation deadlines; tests retain their limits.

New phase manifest2 uses a256 KiB total request/128 KiB inline-body cap; legacy logical requests and old phase manifest1 remain64 KiB, with all proofs64 KiB. reserveReferencedMutation binds exactly one original Attention outbox row in phase0 (deliver), keeping repair inline. Account/generation/full type/record physical key and envelope hash/bytes are distinct from exact transmitted UTF8 JSONL hash/bytes. The existing4 MiB queue-envelope limit bounds its body without duplicating it in operation history. The body helper and outbox reuse one pure queue codec for complete original scope/schema/source/record reproduction. Outer metadata alone cannot relabel a hashed payload to a new account/generation. Reference rows share the owner/gate transaction snapshot, reproof outside IDB, then exact final state recheck; missing/replaced unfinished bodies hold. Only fully verified logical/phase proofs permit terminal metadata reads without the old body; readEffect refuses terminal operations. Missing queue data is never itself a settlement receipt. A later sameUUID/newpayload cannot acknowledge an old body. New reserve APIs emit manifest2; recover manifest1 through original stored reads and phase CAS, never reserialize it or change its nonce. The reference tests cover admitted large events, large policy encoding, restart, both scope relabels, body replacement/loss, version bounds, quota and deadlines. Default sender integration and bounded terminal archival remain integration gates.

The opt-in typed JSONL receipt transport seals generic json() ingest and itself materializes original body, fresh-proves owned target/control schemas and original bindings, and requires live UUID tags with matching owner metadata. Missing tag ownership holds; UUID liveness alone is insufficient. Typed preflight reproduces referenced Attention/canonical policy records and the complete fixed native action plan; unknown native served-schema assertions hold. Arbitrary inline source records cannot bypass capture reproduction. Pin and API-prove the exact POST bearer before guarded CAS; that CAS is the last authority await before one fetch. Use exact original JSONL, canonical Event/DeletedRecord path, sole api_version=v1, no redirects or retry. Recheck current gate/JWT, same pinned API principal and native protection after complete receipt parsing. A whole monotonic/timer deadline and cancellation prevent late issuance.200/201/202 with bounded string upload_id returns a receipt only; loss/ambiguity retains issued/UNKNOWN. It never verifies phases or removes queue rows.

Native receipt DNR protects Event hex/hyphen suffixes as a deliberate superset under the exact HTTPS API/literalroute/POST/owninitiator/query; full UUID regexes exceeded Chrome's compiled-memory bound. Strict canonical UUID authority remains in transport/journal. Require all four native rules; no unprotected fallback. Synthetic temporary-extension reload cleared dynamic rules and required explicit fixture setup, so production installation persistence is unproven. Native QA must include a protected-vs-unprotected identical encoded-response differential, not only fake fetch headers or rule readback. The typed tests cover identity, exact large bodies, once-only issue, native identity/schema, receipt ambiguity and timeout. Policy permission/reuse, before/after policy checks, exact readback, atomic settlement, backend quiescence and default/Safari integration remain separate gates. A receipt never proves delivery/absence.

Exact browser row-level userid/fulcra_userid, when exposed, must each match the captured account. A contradiction is UNKNOWN, never silently dropped into absence. Submitted-field matching uses the admitted payload's 4 MiB UTF-8 bound.

The opt-in exact browser record reader uses full Event/Metric plus exact UUID instant selectors, at most 32 IDs per operation, under V1Http's captured account and current API-principal checks. Only a complete successful JSONL 200 can return absence. Partial/paged responses, conflicting exposed owner/totals, malformed suffixes, duplicate keys or identities, unrequested rows and stream errors fail closed. Keep decoded-body/deadline bounds and static errors; never expose parser payload fragments. Frozen results and submitted-field/time comparison are one-read evidence only. No queue clear, POST, replay policy or historical coverage follows from them. The development contract and synthetic tests carry bounds and supported semantics; default writers remain unchanged.

The permanent exclusion specification has one packaged contract shared by Python and browser pure helpers. Preserve its existing creation fingerprint and required-field order. Attention and exclusions use the same closed Event proof with only those two static families; the exact exclusion-reason string set is order-independent but cannot gain a restore state. Pure schema/spec checks create no policy, owned binding, exclusion/absence evidence or upload authority. Run both contract/schema suites when changing this resource or shared proof; verify the Python wheel includes the JSON before packaging the app.

The pure browser exclusion codec shares Python's stable target primary, UUID5 and flat point-record fields. It permits canonical Event/Metric targets, forbids self-control/restore, and captures action/time/evidence before hashing. Encoding grants no current policy or durable-action proof. The development contract defines evidence/JSON limits and the shared synthetic Python/browser vectors. The lossless instant helper supports Python microsecond timestamps for control records and generic readback; Attention capture retains its millisecond-only fence. Never round an existing control timestamp or reject it merely because Python retained microseconds.

The opt-in browser control binder discovers renamed policies from the complete input inventory and closed input schemas, never a name-only catalog miss. Unpinned discovery scans at most64 Event schemas including retired rows; unreadable/plausible incompatible policy or ambiguity holds creation. Explicit/private original full UUID pins retain fresh ownership, input/served proof and final unchanged-input checks. New bindings repeat discovery before publication. Use one <=10s monotonic budget and <=8s/remaining HTTP reads; overrides cannot extend the HTTP instance budget. An overall timer bounds local waits; deadline checks inside journal callbacks guard local creation writes. A submitted receipt retains identity but cannot bypass first-binding discovery on retry. Preserve known receipts and unresolved intents; never retry a possibly dispatched create or replace a known UUID with a new empty policy. The binding tests define recovery and race behavior. This grants no current replay permission, native absence proof or default sender authority.

Both browser binders retain verified creation receipts against their original durable reservation even after an account transition. This historical write never creates an intent or resolves authority. It requires the original account, specification fingerprint and reservation generation. A contradictory known UUID commits a durable conflict retaining both identities before returning an error; ordinary reads/resolution/replay refuse it and no reset is provided.

The opt-in browser policy reader requires already resolved original authority and uses read-only verifyExclusionV1 before and after protected exact policy reads. It never calls setup to repair missing/downgraded intent. The journal's requireCreation predicate checks account/gate/key/fingerprint/control/original generation inside one read transaction. Reconstruct every returned policy row, reject supplied owner contradictions, and require unchanged schema/reservation context. The development contract and tests define limits and late-callback behavior. Results are one-read evidence; writers still require before/after-write policy checks and a mutation lease. No deletion, queue settlement or default sender integration follows from this helper.

Python's shared v1 record reader uses the same response-completeness gate for exact IDs, source windows and latest previews: require exact requested scope and unambiguous 200; reject redirects/history, partial/paging markers and conflicting exposed owner/totals. Request identity encoding and reject encoded replies; eager gzip decoding may return empty or complete-looking data without a valid trailer. Never turn a degraded read into absence or replay permission. Strict JSONL parsing rejects duplicate keys, malformed suffixes, nonfinite values and invalid Unicode; only ASCII blank framing is ignored. The buffered parsing contract explains the limits: eager HTTP loading/decompression has already happened, so these checks are not a raw-wire/allocation/deadline bound. Run the shared reader tests and source/policy integration suites when changing this gate.

Python's permanent policy helper captures an exposed canonical store.account_id and checks it around lookups, including empty results. Supplied policy-row owner metadata must match that known scope; unknown scope or contradictions hold. Generic record enrichment comparison elsewhere remains separate. The creation journal validates intent states/full destinations and atomically prevents concurrent resolution from replacing an original UUID or healing malformed state. The shared contract and its linked policy/journal tests define this setup behavior. Collect policy transport now uses a separate read-only verifier around each policy GET/POST, including checks after source uploads: existing resolved fingerprint/full UUID, current owned/served proof, final owned/account/local-binding recheck and unchanged schema hash across transport. A cached string alone never proves absence; reads never run setup/adoption or recreate a lost journal. Run the authority integration tests when changing this boundary. Writer mutation leases and controlled old-writer cutoff remain separate requirements. Owned-list and served-schema proofs share strict identity-only, no-redirect JSON reads with exact endpoint/owner/partial checks. Duplicate keys, nonfinite values, numeric assertions changed by parsing and malformed supplied input schema hold; a supplied userid must agree with the captured account too. The canonical contract documents the decoded parsing caps and remaining limits. These schema reads must not fall back to a generic response.json() or a redirected alias.

The shared v1 client has an optional expected_schema keyword on validate_records and ingest. A supplied full schema requires an explicit nonempty captured account_id; None keeps the default behavior and ignores that account argument. The public strict served-schema reader owns token-account proof. Each nonempty pinned call compares and validates one fresh full served snapshot; locally checked empty calls perform no I/O and prove no remote equality. The canonical contract defines bounded input capture, full JSON equality, representation version and remaining limits. No production caller is activated and no historical replay authority is granted. Run the shared seam tests, public proof-reader tests and Collect session/policy authority integration suites when changing this seam.

The opt-in Python transport observers retain actual strict record/schema/receipt facts through the shared v1 and schema boundaries. They require explicit original/account/ID context, the same guard and budget at every SDK/HTTP leaf, exact sink acknowledgement and a retained-attempt event allowance of at most 128 slots across reopen. Receipt and issued-checkpoint capacity are separate; complete buffered responses retain their pre-reserved audit slot after expiry without a fresh authority/token/network guard. No later action follows from that retention. Canonical bytes, inert policy/assessment/history types and stored retention modes grant no coverage, ownership or production replay authority. Production SDK hidden refresh/retry accounting, real retained persistence, B1p owned-policy producers, production historical reconciliation and Collect wrappers remain held; this component activates no production caller. The canonical contract documents exact call shapes, context projections, body/schema hash distinctions, header allowlist, strict observed receipts and buffered/outer-envelope limits. Run the observation tests, reader/default tests, schema/import tests and existing session/policy integration suites when changing this unused surface. Preserve ordinary/default and Task A pin behavior, one final served-schema snapshot and one POST/no retry.

The inactive historical verifier capture now shares the existing read-only verifier and actual observed HTTP leaves. Its private transport constructors unconditionally refuse; tests alone compose synthetic storage/admission/gates. Runtime capture/inspection returns untrusted bytes and facts, never an owned-policy issuer. Preserve the exact7+2+7 charges, same served schema and retained attempt allowance; transcript attachments occupy the started proof slot and uncertain writes never refund it. Whole-chain bytes are checked before each fixture storage mutation, and staged linkage compares exact canonical bytes. The canonical README owns raw-byte/linkage/limit details and H1–H5 production holds, including the still-unqualified original journal opener and auth revision/gate. Run the new transport/transcript regressions and common/Collect suites when changing these seams. No Collect constructor/caller, production namespace, real auth gate or historical apply is activated; ordinary/default methods stay supported.

The unused synthetic historical reconciler now consumes B1a observations and re-exports the same existing HistoricalDelivery. It is singleton-only, defaults to no submission, retains separate control/target assessments and checks the same guard/budget through every nested request. Matching original-payload positives remain disqualifying across attempts, terminal outcomes, audit retention and later deletion; a mismatch is retained conflict evidence. Every normal return requires one outcome callback with fresh retained history, atomic fixture CAS and independent event/slot/state readback. Issued/outcome, assessment and observation events share the retained maximum 128-slot allowance; uncertain persistence propagates without retry, refund or a clean result. All owned binding factories/resolvers, authority, external history, fencing and lifecycle persistence implementations remain solely in the test fixture. The fixture-only exclusions.binding_proof capability is required at entry; production RecordExclusions does not implement it. Its full-row validator is the one private pure core shared with the unchanged live policy read. No production caller, authority issuer, policy observer, real persistence/CAS (C), driver (D) or actual historical apply is activated. The canonical linked contract owns exact signatures, classification, hash domains and limitations. Run the historical/policy tests plus the existing common and Collect session/policy/outbox suites before shipping a change to this seam; ordinary live repair and replay behavior must stay unchanged.

Chrome v1 record reads require verified identity/encoded-response protection. Fetch accepts some truncated gzip streams, so decoded EOF cannot prove absence. Explicit setup owns fixed rule IDs1002/1003 for this extension's production record GETs and1004/1005 for typed ingest POST receipts. Reads and writes assert the complete four-rule state without installing it. Only the exact Auth0 rule 1001 may coexist; unknown/session/static rules refuse. Never silently clear other policy or downgrade on unsupported Chrome response conditions. Keep protection checks inside the HTTP deadline and around body consumption; a late or encoded result cannot acknowledge queued work. Before records can be read, the typed reader must select this protected JSONL leg; generic JSON permits only canonical catalog paths under /data/v1/ and refuses encoded path aliases before fetching. Before setup changes, publish the caller's new account/config generation. Safari needs its own native transport proof. The development contract and tests define the API support and bounds; default senders remain unchanged.

Historical Collect migration (development)

The offline foundation binds an immutable account/source/target/schema/codec/range plan to a separate private ledger. A separate read-only raw HTTP reader now retains bounded private response artifacts. A separate paired export driver adds bounded library orchestration; production export/apply/CLI and runtime account authority remain separate work. Supply a captured client and fresh consent/origin guard returning the expected account UUID; never instantiate an ambient fallback client. Reads enforce the production HTTPS API, explicit account/type/range, no redirects, a 64 MiB raw-body cap and default 30-second request deadline/socket timeout. A pass UUID cannot change plan scope. Each request gets a new private attempt with a fsynced manifest before HTTP, raw bytes before parsing, and a hash/EOF receipt only after full flush. Request identity encoding; retain encoded responses without decompressing and refuse them. Check deadlines on raw chunks, including compressed empty-output blocks. Recheck retained size/hash against the EOF digest before parsing the same bytes. Scan each raw object before JSON allocation (1 MiB, 64 container levels), and bound parsed snapshots to 4,000 rows/16 MiB canonical row JSON. Larger responses stay raw artifacts needing a narrower read, never silently discarded rows. Preserve failed/partial attempts; never reuse an orphan body as a complete read. JSON wrappers, duplicate keys, lossy/non-finite numbers or invalid Unicode fail visibly. A receipt/result always has coverage_complete: false; EOF is not provider coverage. No credentials or arbitrary header values enter artifacts. Version-3 receipts retain known partial-header names, bounded total/length counts, and the optional canonical response account UUID (or absence/invalid marker). An explicit malformed, duplicate or other-account response header refuses body access; retain its incomplete receipt with no transport EOF or decoded-body claim. Absence preserves request/guard authority and adds no account proof. Explicit partial/pagination evidence or malformed/contradictory counts refuse initial reads and later artifact consumption; verification rechecks the account fact and binds the original receipt hash as well as the body. The driver requires an explicit, externally justified provider contract (version: 1, semantics: complete-below-row-cap, row_cap: 1..4000, nonempty basis); it supplies no default. The public legacy endpoint has no cursor/total count/ceiling attestation, and matching two reads cannot invent one. Pass UUID, plan, contract and export protocol bind immutable version-3 pass/proof tables in the private ledger. Old v1/v2 evidence may have discarded response-account facts and cannot resume or certify current-format coverage; a new pass refuses existing unbound windows. Preserve old artifacts; use a fresh authorized pass/ledger for new evidence. Indexed next-open reads avoid prefix-rescan starvation; a nonblocking owned-file lease serializes runs. Reopen and hash/scope-check both raw artifacts before consuming them. Equal multisets below the asserted cap conditionally seal; capped/unequal pairs split with overlap, minimum saturated/unstable or failed reads stay open. Retain all distinct versions from successfully committed pairs, including parent versions missing from later children (at most 8,000 versions/32 MiB canonical JSON per pair). Pair proof + raw versions + seal/split are one transaction. Metadata proof reads do not audit artifacts afresh. Runs reserve both request timeouts, cap at 64 windows/300 seconds and report queue progress, never final coverage. The ledger coverage fold is conditional on the supplied provider assertion. Its lower-level status can still summarize old stored windows; that metadata is not current-format proof or raw-account/integrity verification. The versioned driver guard is mandatory before reuse. Final raw audit, cutoff/queue/late-delta and disposition gates remain mandatory. Raw variants and overlapping observations are retained; missing IDs quarantine. Never treat an HTTP 200, capped read or observation count alone as coverage: sealed windows bind the exact integer ordinal sequence 0, 1, …, count−1 and ordered observation/raw hashes (fractional ordinals fail sealing and resume); explicit narrower children replace saturated parents, and complete leaves must cover the whole range without open reads. One-row capture does not scan all windows; the coverage fold has a 100,000-window limit. Whole-window capture/seal is atomic (1 MiB per row, 16 MiB total), as is child creation plus parent split. Raw response artifacts must be retained first; a caller assertion is not provider proof. Split operations read only the parent/children; window(id) gives scoped resume metadata with no raw-audit claim. Unknown schemas/statuses fail visibly, not empty. Canonical raw rows cap at 1 MiB; oversized input fails without sealing, so export orchestration must preserve its raw artifact. historical_complete stays false until actual conversion, cutoff/queue and late sweep gates are implemented and verified. Original remote records remain intact. Status says raw_integrity: "not-scanned"; coverage receipts do not certify a fresh raw-content audit. entry() hash-verifies raw content before consumption. Window bounds reject inexpressible submicrosecond instants and invalid timezone offsets; shared v1 readback compares fractional RFC3339 instants exactly without datetime truncation. Media codec v1 supports flat typed DurationAnnotation; v2 supports the API reader DTO with strict account/definition/prefixed-source proofs and declared legacy_record provenance. Default media specs stay frozen; media_history_spec is a separate opt-in key/name, not a silent schema edit. Both preserve declared fields and the shared live/history UUID mapping. Unknown envelopes/markers, ambiguous identities and lossy output quarantine; unfrozen schema references fail without network retrieval. Schema 2 retains converted proposals with recomputable codec proofs; conflicting payloads for one target atomically quarantine every prepared variant (group bound 1,000 rows/4 MiB), while identical proposals converge. Every peer is codec-verified before equality decisions; converted reads recheck conflicts. A prior returned proposal is never upload authority: later variants can invalidate it. See the linked README for supported codecs, boundaries and remaining completion gates.

The static codec registry retains the eight media IDs and lazily loads the optional Journal reader codec. Unknown/unavailable codecs fail before conversion row work; raw-only export and reopen remain possible. The new UNIFIED_JOURNAL_SPEC is opt-in local revision 2, still an API v1 Event: existing JOURNAL_SPEC, writer defaults, creation fingerprint, pins and pending recovery remain unchanged. Do not activate it by relabeling cached destinations or use nullable historical enrichment to weaken live-source validation. Its complete raw provenance, independent payload bound and all-branch reference rejection are documented in the canonical Day One guide. Pure conversion grants no schema creation, apply or completeness claim.

The daemon (Collect)

  • Foreground without native menu auto-launch: use fulcra-collect daemon --no-menubar for source/server QA, following the source invocation for workspace dependencies. Ordinary daemon keeps auto-launch enabled. This invocation-only option skips the native menu startup hook; profile ownership, control socket, web server, quiet authentication preflight, scheduler/worker config and consent checks, and shutdown continue normally. It is not an offline, no-auth, or no-network mode.
  • Single cooperating daemon per effective profile (development branch): profile ownership uses the persistent private daemon.lock before migration/control/auth/dispatch. A busy lease exits 75 with a static diagnostic; unavailable ownership exits 1. Busy is not holder-health proof. Ownership lasts until process exit even if serve() unwinds; do not restart in-process or delete/truncate the lock file for recovery. No stale PID authorizes takeover. Stop/reconcile older unleased daemons and workers before adoption. The local cooperative guarantee excludes direct/legacy writers, detached orphans and cross-host writes; it neither proves quiescence nor retires workers. Launchd KeepAlive/systemd Restart remain unchanged and can retry a duplicate. Source verification is separate from signed-app/runtime acceptance.
  • Persistent service failure status (development branch): the cached-status contract records owned nonzero exits through ServiceSupervisor.tick(on_exit=...) and OS launch failures through original-revision local fences. Use the atomic status-only writer; never retry an uncertain increment, infer provider health from an exit, or expose unscoped old-account state after dropping an UNKNOWN overlay. The overlay is volatile; restart is not durable reconciliation. Status/observer paths must stay free of credential and provider reads.

Trakt's current setup separates developer API apps from Connected Apps. See the canonical media guide for current and legacy links, Client-ID-only PKCE at auth.trakt.tv, retained legacy refresh credentials and exact saved callbacks. Choose a Development app for Collect's exact local HTTP callback; Production requires HTTPS. Deployed form support is verified; actual new/legacy account sign-in remains release QA.

  • Day One v1 (development branch): the Journal writer uses v1_destination_ids.journal, strict Collect auth, immutable pending batches and replay exclusions. It preserves import-once behavior and the case-sensitive legacy source hash; reruns do not overwrite cloud edits. Old annotation selections need explicit mapping. Preview creates no metadata or receipts. Attachments remain unuploaded. The writer is included in the published 0.1.5 app; source-specific live acceptance and historical conversion remain separate. The standalone CLI now shares the v1 writer with explicit CLI/env auth and fresh API account proof; Collect authentication remains strict and separate. --destination Event/<UUID> selects an owned compatible target; legacy bare IDs require explicit mapping. Real invocations use fixed profile-local cli-dayone state, a bounded invocation lease and shared task/account-record leases. Resume original pending work before reading/discovering sources, empty returns or metadata. Changed account/options hold without discarding pending evidence; issued absence never permits resend. Default --local-db binds a selector, discovers the current default only after recovery, and may select another DB later; explicit --db-path binds an absolute path. Dry-run reads local input only, without auth/profile/DB/provider work. The annotation-definition/GenericEvent Python API raises migration errors; use DayOneFulcraClient.open(settings) and JournalWriter.resume()/run_import() with original entries. The explicit runtime pins the profile before state access and uses the same DB9 rollback protocol; its serialization does not extend across profiles/hosts. Ordinary Day One tests deny external HTTP and use synthetic transports.
  • Gmail account/delivery (development branch): the captured transport binds Google reads, Files, canonical coord companions and local receipts to fresh Collect/source consent. The app bundles coord-engine; never restore default CLI credentials or a subprocess relay. Exact directive-file readback precedes relay-done; an empty search envelope is not delivery evidence. Ledgers/cursors include the destination principal and actual action target; old source-only state is retained, never adopted as proof for a new target.
  • Reminders/Todoist account/read consent (development branch): the task engine contract checks captured read consent in preview as well as live runs. Actual callers use CollectRecordSession and inject shared Files HTTP into the task vault. incomplete HTTP reads remain UNKNOWN and cannot authorize file or checkpoint writes. Never restore a frozen bearer or selection-only guard. Retain task generations, completion journals and the final mutation leases. Todoist guards each HTTP request/chunk and observation checkpoint; Reminders guards each bounded bridge invocation. In-flight native calls can finish; revoked results are discarded.
  • Apple Notes: included in the macOS bundle and registry fallback. Use the wizard for Full Disk Access verification and one-way import. Snapshots use a bounded SQLite online-backup subprocess; entity IDs are resolved from Z_PRIMARYKEY. Preserve unowned Markdown and refuse missing/ambiguous fences. Keep real library metrics and source data out of public code, tests, commits, and reports. On the development branch, account/consent binding uses an explicitly injected Collect Files adapter in sync/reconcile/writeback, never default CLI credentials. Guards cover source reads, each Files request and final leased writes (including native writeback); reconciliation caches include destination account. Local-only sync preview stays cloud-free; reconciliation reads require Collect sign-in. It remains Files-only.
  • Bundled runtime: the Briefcase app supports --collect and --fulcra CLI dispatch plus an internal --notes-snapshot worker. Build-generated sibling launchers supply fulcra-collect, fulcra, and fulcra-api without a developer venv. Workers must use the bundled launcher, never Python -m flags on the native app executable. The build installs these before signing. Before any bundled dispatch, the entry point sets SSL_CERT_FILE to the included certifi roots only when neither CA-file nor CA-directory override is present. Embedded Python may lack OpenSSL default roots; urllib/Auth0 needs this explicit default. Preserve operator trust overrides and TLS/hostname verification; never work around this with disabled verification. Missing roots fail before auth. Source/venv trust is unchanged.
  • Public-input bundle QA: follow the invocation-bound stages and stage helper, with canonical sanitizer at the existing raw/postbuild/check-only positions. Prepare BEFORE CREATE; local launchers retain the exact legacy tuple, while cloud uses the closed source-owned cloud-xcode16.4-arm64-v1 qualifier and controlled-install-and-bind for PREPARED generation1 → BOUND generation2 before raw sanitize. Profile/tool cross-binding is mandatory at start/context/current/native entries. The cloud ownership bootstrap consumes a durable attempt before full recipe validation; any later UNKNOWN requires a fresh nonce/run directory/app namespace after inactive-lock recovery, never retry or saved-proof adoption. First admission needs the live one-use witness; descendants use their independently owned digest chain. The typed observer alone allows256MiB/file, with544MiB/60s for two OS passes plus six ordinary128MiB tool passes; actual toolsets that cannot fit fail before producer effects. One original300s deadline starts before ownership bootstrap and spans all reads, sweeps, publication and final admission; nested operations never renew it, and commands reserve kill/reap time within it. Every presented live witness is revoked even on early source/selector failure. The exact source-owned Python b10 linker-data requirement stays outside the unchanged privacy catalog: owned expected alias selection requires its presence, regular type, mode and bytes at local/cloud binding and full verification, plus exact support-member consumption before the config skip. Only the additional canonical Collect outer alias activates the two fixed PyObjC debug companions: their complete wheel/member/fixed-slice origin and current bytes stay exact, including full-hash signing snapshots before native parsing. Only these selected exact data leaves leave the native target set; full inventories, privacy and framework/app verification remain. See the linked package contract and pure source-data record. Exact limits, pinned environment/installer, SDK scope and local compatibility live in the linked package contract. Actual cloud app/N1 qualification remains required; pure tests do not grant it. Preserve the stage ordering; only the controlled BUILD/sign wrappers can mint a signed generation. Current I/H live in trusted entry/completion plumbing (COLLECT_PROVENANCE_CONTEXT), never candidate receipts or saved old contexts. Its schema2 envelope is capped at 32 KiB and independently binds immutable metadata (0600/write-once/8 MiB/no head); remaining head growth through gen64 and current environment/argv capacity are checked before receipt publication. The build uses a fresh external private run directory and parent-owned private completion FD (COLLECT_PROVENANCE_RUN_DIR, COLLECT_PROVENANCE_COMPLETION_FD) when COLLECT_PROVENANCE_REQUEST selects the constrained path. It must be a writable pipe, concurrently drained through bounded length framing and EOF; regular files/partial frames fail, and old full contexts require fresh entry. Lost authority restarts fresh; no receipt adoption or scope-lock stealing. Preserve strict no-provenance fallback, source/wheel/support/inventory gates, and independent review. Exact current app inventories precede broader transform comparisons; only whole unchanged public intervals receive marker permission. Framework parent-file aliases require component-by-component ordinary-inventory proof inside the same framework before complete inventory emission; canceled links/missing paths, temporary escapes, non-file leaves or changed identities remain UNKNOWN. Qualification grants no content exception or actual-app acceptance. Source-derived ad-hoc per-target policy and fresh absolute codesign observations are required. Bind framework/nested-app executable aliases to pinned origin Info.plist and exact scoped paths/version links; all final alias policy fields agree in both BUILD/sign sets. Unknown geometry stops before mutation; unknown compiler/tool/ entitlement forms stop UNKNOWN. Runtime/help/cache boundaries mark mutations DIRTY and require controlled re-sign/fresh final signed checks. Receipts/inventories are 0600 write-once, capped at 256 KiB/8 MiB; native verification 30s/command,300s total,1 MiB/command; BUILD900s/16 MiB; timeout/cap kills and reaps the whole group. Actual cloud N1 remains UNKNOWN: pure/fake-tool GREEN is neither native qualification nor release permission.
  • AppleScript writeback is experimental: it additionally requires explicit writeback_enabled = true and refuses all attachment types. Do not enable it as part of ordinary Notes setup.
  • Plex/Jellyfin receiver port: setup exposes port as a typed port setting (default 8765) on the common topology step; both local and LAN URL examples instruct the user to substitute their selected port. Preserve the LAN token guard. See the receiver plugin.
  • Setup does not imply sync consent: entering the final wizard step must never enable or run a plugin. Use its explicit start action, persist the displayed preview mode before enabling, and fail closed if settings cannot be saved. Run node --test packages/web-ui/tests/*.test.cjs when changing wizard navigation or first-run behavior. Next displays Saving… and coalesces duplicate clicks while a save is pending; navigation releases Next on the new step and invalidates late advancement and subsequent Enable/Run requests. Preserve both onboarding/Configure bindings and the navigation regressions when changing the wizard controller.
  • Worker deadlines cover process exit and both pipe EOFs. The runner uses one monotonic budget, bounded output tails and no drain threads. On timeout or failed draining it stops the owned process group even if its leader exited, with at most 0.5s direct-child reaping. Escaped separate-session helpers are not chased; their pipe handles cannot extend the deadline. Keep the real descendant regressions.
  • Run it durably as a launchd agent, NOT a backgrounded shell process — a foreground/& daemon dies when its terminal or session ends. Install + load: uv run fulcra-collect install, then launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.fulcra.collect.plist. Restart: launchctl kickstart -k gui/$(id -u)/com.fulcra.collect. Stop: launchctl bootout gui/$(id -u)/com.fulcra.collect. Logs: ~/Library/Logs/fulcra-collect/.
  • Subcommands: daemon install status run enable disable set-credential set-setting set-interval plugin doctor. There is no start; doctor runs the pre-flight diagnostic.
  • set-credential (keychain) and set-setting (config.toml) are the headless pair for configuring a plugin without the wizard. set-setting validates against the plugin's declared required_settings and refuses any key declared as a Credential — every mistake it could otherwise make (typo'd plugin id or key, out-of-range enum) writes successfully and is then never read, so it must fail loudly at the CLI or not at all.
  • Config dir ~/.config/fulcra-collect/: control.sock (the UDS the menu-bar
    • CLI use), web-url (default http://127.0.0.1:9292), web-token (Bearer for the web API).
  • Control socket paths are bounded to 104 filesystem-encoded bytes including the terminator. Long or multibyte profile paths retain a control.sock symlink to a private per-UID socket. The completed system-temp candidate must fit; otherwise /tmp is used. The selected per-UID child must be an ordinary current-user-owned directory before chmod/socket replacement; aliases and foreign owners fail visibly. Keep directory mode 0700/socket mode 0600 and client indirection.
  • Plugin authors needing independent durable cursors/state use RunContext's kv_get / kv_set / kv_update / kv_delete API. It is isolated by plugin ID and backed by state.db; values must be JSON (64 KiB maximum, 256 UTF-8-byte keys). Use kv_update only for quick, side-effect-free atomic transforms because it holds SQLite's writer lock while the callback runs.

Freshness: run status cannot tell you a source has died

last_run / last_outcome / consecutive_failures answer did the plugin run, never did it collect anything — a source whose upstream goes quiet keeps exiting cleanly with last_outcome="done", so every health signal stays green while the data stops. freshness.py supplies the missing half from two independent clocks: last_yield_at (daemon clock — catches "runs fine, produces nothing") and newest_item_at (source clock, monotonic so a backfill cannot drag it backwards — catches a plugin that keeps writing while upstream is frozen). Plugin authors: pass observed_at=<ISO source timestamp> to ctx.annotation(...) (only the plugin knows when the thing happened upstream), and opt in with freshness=FreshnessExpectation(max_yield_silence=…, max_upstream_lag=…) — monitoring is opt-in by design (a bound guessed from default_interval would cry wolf on legitimately rare sources; set max_upstream_lag above normal quiet periods). A plugin that has never yielded reports UNKNOWN — deliberately neither healthy nor stale; collapsing "we have not looked" into "we looked and it is fine" is what let a four-day outage read as green.

launchd PATH gotcha

launchd runs the daemon with a restricted PATH (/usr/bin:/bin:/usr/sbin:/sbin) and does NOT source your shell profile — so ~/.local/bin (where uv tool install fulcra-api puts the fulcra CLI) is invisible. Any code shelling out to the fulcra CLI must resolve it via credentials._find_fulcra_cli() (PATH → ~/.local/bin → homebrew), never bare shutil.which("fulcra").

Second-order gotcha (bit the gmail relay twice): resolving your OWN binary to an absolute path is not enough if that binary shells out further — coord-engine itself execs fulcra-api by bare name, so under the daemon's PATH every relay emit silently no-oped for five days. When you shell out to a tool that itself shells out, pass an env whose PATH includes the install dirs AND set EnvironmentVariables.PATH in the daemon's launchd plist. The development Gmail relay removes that subprocess chain: it embeds the bundled engine with an explicit Collect transport; see its account/delivery contract.

HTTPS trust in packaged Collect

  • fulcra-collect bootstraps missing compiled-in OpenSSL CA paths locally before subcommands, using the installed certifi bundle for SSL_CERT_FILE and an unset REQUESTS_CA_BUNDLE. Workers and CLI children inherit the environment. Preserve operator-supplied values and certificate verification; do not solve bundle trust failures by disabling TLS checks. Existing platform CA locations are left alone. This does not repair Keychain ACLs or prove signed-app HTTPS; see the Collect README.

Keychain

  • User secrets live in service fulcra-collect:user; plugin secrets use fulcra-collect:<plugin-id>. Native macOS background reads use macos_keychain.py in a disposable child using the same executable/signing identity. Modern per-query flags alone do not suppress legacy file-Keychain ACL prompts: the child also disables interaction for its own lifetime. The daemon/UI process's setting stays unchanged. Only item-not-found is absent; denied, locked, pending and unreadable items remain UNKNOWN. Configured non-native keyring backends retain their own behavior.
  • credentials.py bounds reads to 3 seconds, one pending OS call per item and 16 per process. Timed-out calls retain their slots until completion; fresh auth guards never reuse a late result. Local writes/cache invalidation fence older reads. Optional source credentials stay optional for modes that do not use them.
  • An authenticated explicit POST /api/plugin/<id>/credential/<key>/authorize (control command authorize_credential) validates declared key/scope and requests access to the existing item. Configure shows Allow Keychain access for unknown credentials. A subsequent quiet read must succeed; one-time Allow alone does not prove background access. Always Allow remembers the current app identity. No secret value is returned or replaced.
  • Core sign-in access recovery uses the separate authenticated explicit POST /api/fulcra/auth/keychain_access, restricted to bearer-token and oauth-credentials. Unknown auth status routes to Settings for access recovery; it must not imply expired or missing credentials. Reinstallation or a changed signing identity may require another explicit grant. Preserve existing items rather than deleting them to repair an access problem.

Collect distribution resources

Collect distribution builds require complete prebuilt SPA/docs inputs. The canonical package contract and build hook define the archive-only _build_resources snapshot, existing wheel _bundled layout, lexical archive markers and fail-closed missing/symlink/special-file handling. Never temporarily stage assets under fulcra_collect/_bundled: its presence changes running resource selection. Build tools may reject/read malformed PKG-INFO before this hook, so backend errors are not hook-execution evidence. Use the disposable packaging tests for build parity/failure proofs; do not delete/chmod/rename live assets to make a negative case. Input immutability, cached offline backend, frontend preparation and later signed-app/installed acceptance remain distinct prerequisites/gates.

Menu-bar app

  • Launch from a GUI (Aqua) session: uv run --package fulcra-menubar python -m fulcra_menubar. Not from SSH/detached shells, or the status item won't appear. Under Homebrew Python the bundle id is org.python.python (use that for computer-use / TCC grants, not com.apple.python3).
  • It talks ONLY to the daemon over the control socket; it never reads the keychain. Auth state, tracks, and plugin status all come from the daemon — a stale UI usually just needs a relaunch / reopened popover.
  • Bundle-requiring macOS APIs (UNUserNotificationCenter, etc.) raise an uncatchable NSException when run unbundled (python -m from a venv) — try/except can't recover it. Guard with _notify_macos.running_in_app_bundle(). The shipped app is bundled via Briefcase.

Sign-in & first run

Full first-run walkthrough + troubleshooting: docs/TESTING.md. Diagnose a live install with uv run fulcra-collect doctor. Its coverage contract includes a static WARN for unchecked v1 destination schemas and delivery; configured writers own that validation/readback. Exit 0 means no diagnostic FAIL, not acceptance of a source's schema or records.

coord-fold — the coord-on-annotations fold engine (packages/coord-fold)

Canonical home for the durable facts about packages/coord-fold (its plan docs/superpowers/plans/2026-09-04-coord-fold.md and spec docs/superpowers/specs/2026-09-04-coord-annotation-bus-design.md exist only on the unmerged coord-fold-plan branch, not on main). Ship-gate rule: every PR touching the package updates this section or states "no change needed".

What it is. A SEPARATE package (not a module inside coord-engine): coord_fold/{events,transport,channel,checkpoint,fold,cli}.py, each owning exactly the symbols the ownership manifest in tests/test_structural.py names. Its import graph never reaches coord_engine; pyproject.toml declares no dependency on it. Dependency direction is one way: coord-engine's old side (Tasks 12–14: seed export, dual-emit, comparator) may import nothing from here and here imports nothing from there.

The reader/writer boundary (spec §3.4, corrected). The transport is a two-method Protocol; CliPointerReader and CliPointerWriter are unrelated classes with disjoint surfaces and NO enumeration method. §3.4's original wording implied that the type "stops os.listdir"; corrected: a type stops a method call, not os.listdir — nothing in a Python type prevents a caller from enumerating. The guarantee that enumeration does not happen is G29, below, not the type.

Six verbs, three exit codes (coord_fold/cli.py): emit, fold, claim, release, close, status. RC_OK=0, RC_REFUSED=2, RC_UNKNOWN=3. Refused means the verb declined on evidence it read; UNKNOWN means a read did not answer and nothing was concluded. A capped fold pass is NOT an error (G25): it applies what it read, advances the cursor to the last applied event, reports unread_events: N and exits 0 — a remainder bounded by new events, not a failure. The only fold error is zero progress while events exist. The string degraded never appears on any output path (G11; tests/test_no_degraded_vocabulary.py enforces it): unreadable_pointers: [slug] is UNKNOWN (exit 3); unread_events: N is a remainder (exit 0). An unknown never reads as clear.

Cursor rules (G26, G31). The cursor is the recorded_at of the last OBSERVED record before the first UNAPPLIED RELEVANT event — never now, never past a gap. Records that are unparseable, foreign-schema, or addressed to someone else are observed and passed, never re-read. Checkable consequence, made a test: re-running a fold from the stored cursor yields the same open set. Lost-update detection, not CAS (G27): the store has no compare-and-swap; the checkpoint carries writer and a monotonic generation, the fold re-reads before writing and refuses by name if the generation moved. No compaction, never delete events (G28).

Relevance rule (RULING 2026-09-05, coord-boss blocker a0927018). An obligation belongs to its ASSIGNEE. An event applies to an agent's fold when it is addressed to that agent or to all, OR when the agent itself sent it and it is a claim/release/close (the assignee's own action on an obligation it holds — those are addressed to the open's sender but performed by the assignee, and the assignee's fold must see them or a closed row would stay open forever). An open or note the agent SENT never opens for the sender: a sender's waiting is bookkeeping, not an obligation. The earlier rule applied every sender event too, so every seed leaked into its senders' folds (coord-boss saw 54 of coord-maintainer's opens, coord-maintainer 137 of coord-boss's) and no coordinator could ever AGREE. Both sides — the old plane's obligations/compare-to-fold and coord-fold — ask the question this way. Checkpoint rows carry to (the recipient) since 2026-09-05 so a divergence classifies from the row alone; the field is ADDITIVE, rows written before it lack the key and stay valid, and SCHEMA_VERSION did not move because a bump makes every existing checkpoint load as corrupt and refuses the fleet's next fold. Two residual edges (coord-boss 6f8121fc, 2026-09-05): a broadcast (to: all) opens for every agent EXCEPT its sender; and the mirror turns a v3 directive into a v4 open only when the task doc it points at names an assignee (read once at write time; an unreadable doc mirrors anyway, over-capture over a silent hole) and never for an FYI, because neither opens an obligation on the old plane. Class C (coord-boss 24d545b0): a row already in a terminal status (model.TERMINAL_STATUSES) when its open is emitted — a DONE report born done — opens nothing either, or it would carry an open with no close forever. A checkpoint computed under the old rule is repaired with coord-fold fold <team> --agent <a> --rebuild: it replays the whole stream under the current rule (events are never deleted, G28) and keeps the generation/writer so a concurrent writer is still refused (G27).

Pointer resolution (coord-boss finding 2026-09-05). Emitters write ptr TEAM-RELATIVE (task/<slug>.md); the store holds team/<team>/task/<slug>.md. The READER resolves: coord_fold/pointers.py::qualify(team, ptr) prefixes team/<team>/ onto a bare pointer and passes an already-qualified one through, and both pointer reads (fold --verify-pointers, close --evidence) go through it. Read verbatim, every open row came back absent (a legitimate answer, so nothing flagged it) and the flag whose job is to prove pointers resolve reported 339 of 339 unreadable. No migration of emitted events; every other consumer of this plane (the Linear bridge already does) must resolve the same way.

Record write shape (G13 drill finding, 2026-09-05). coord-fold's writer invokes the real CLI exactly as the engine's record_write does: record <data_type> --api-version <v> --source <sender> with only {note, recorded_at} on stdin. The first cut passed no positional and five stdin keys; the real CLI refused every write (rc 2, Missing argument 'DATA_TYPE') while the proof's fake accepted it, so every coord-fold emit/claim/release/close on the live store returned UNKNOWN until the drill tried one. The proof's store server now refuses the same shapes the CLI refuses; a fake that accepts what the real thing rejects proves nothing.

The four gate files (CI: the always-on Linux uv-workspace.yml test step, plus macOS pytest packages/; and scripts/materialize_plan.py GATES): tests/test_structural.py (ownership manifest, no enumeration, import graph, two-method Protocol, disjoint reader/writer), tests/test_tripwire.py, tests/test_ship_check.py, tests/test_ci_wiring.py; plus tests/test_file_size_ceiling.py (G8: 400 lines per .py under coord_fold/, recursive; the ceiling is documented in packages/coord-fold/README.md) and tests/test_no_degraded_vocabulary.py.

The tripwire is demoted (G30). tests/test_tripwire.py is a syntactic scan for enumeration identifiers and modules (os.listdir, iterdir, glob, …). It catches the plain spelling and nothing else — an alias, a getattr-built name, or a subprocess escapes it by construction. It is kept because it is cheap and true about what it names; it is NOT the guarantee and a green tripwire proves nothing about behaviour.

THE GUARANTEE, in G29's words. The guarantee is behavioural, OS-enforced, and observed at a process boundary. tests/proof/run_proof.py starts a store server OUTSIDE the sandbox (tests/proof/store_server.py: the corpus lives in that process, loaded from a file the sandbox cannot read; it answers only the five fixed request shapes — file stat, file download, get-records, record, file upload — refuses and logs everything else, and logs each get-records with its channel, its since, and the count returned), then runs the PRODUCTION CliPointerReader/CliPointerWriter through all six verbs INSIDE a macOS seatbelt sandbox that denies at the kernel every network endpoint except the store's socket, every exec except the interpreter, every file read outside the interpreter, the package tree and its own temp dir, and every file write outside that temp dir. Five phases: the clean run asserts the exact request sequence with paths, a path allowlist, per-shape bounds, and that no get-records asks from before the cursor the store held at that moment minus the overlap; the attack battery; a file list mutation; the epoch-rewrite mutation; the point-probe mutation — the last three must be FLAGGED. What it proves and no more: in that run the fold reached no store except through observed requests — these specific capabilities were denied by the kernel and the fold still completed. NOT "the fold ran with no capabilities". What it does not claim: that enumeration is impossible to write, that the fold cannot detect it is under test, or that a Python process can hide anything from code running inside it. The measured profile is allow-default with kernel denies on the capabilities that matter, because deny-default aborts the interpreter at startup on the proof host (measured, rc 134). The driver exits 3 (UNKNOWN) where no OS sandbox exists — never green by absence, never softened to a skip; the final line prints host, platform and UTC time. The proof needs a macOS runner: .github/workflows/coord-fold-proof.yml has two steps — one asserts the host has a sandbox (else it is the wrong host, not a pass), one runs the proof and treats exit 3 as a failed job. Linux CI is UNKNOWN by design. No bwrap profile is written until it can be measured.

Trust model of the ship gate (r34). It defends against the mutable tool environment, PATH/env resolution, and world-writable or cross-user temp locations. It does not defend against a concurrent same-user process on the gate host (which could replace the gate itself), and claims no pathname binding against one. Its temp root is a gate-created 0700 directory under ~/.local/state/coord-fold/tmp (an inherited TMPDIR is ignored); the engine child gets its CLI as an absolute path in FULCRA_CLI_COMMAND with an empty PATH; downloaded bodies are checked for owner, mode and non-link status immediately before being read.

Ship gates (ruling 6bb7fa0f, 2026-09-05). Task 1b (the proof) and Task 16 (scripts/ship_check.py: the engine's folded APPROVED result on the EXACT commit, both required reviewers' winning shards quoting git rev-parse HEAD:packages/coord-fold, an approved+pinned engine attested by the gate's own interpreter through a verified-bytes importer, trust roots stated as absolute paths --git/--fulcra-api) gate SHIPMENT, never the start of work. G24: a plan revision is filed only with Task 0 (scripts/materialize_plan.py) green.

coord bus-v4 bridge — Tasks 12–14 of the coord-fold plan (2026-09-05)

The old bus (bus-v3) and the new annotation-native plane (bus-v4, folded by packages/coord-fold) run in parallel until cutover. Three engine verbs make the parallel run measurable; none of them changes what the fleet acts on today.

  • Channel. bus-v4 is the data type named in team/<team>/_coord/bus-v4/records.json (data_type, api_version). No config → nothing mirrors, nothing seeds. Never hardcode it.
  • Dual-emit (Task 13). coord_engine/dual_emit.py::mirror is called once at the end of records.emit_event, the engine's single write chokepoint, so every bus write is mirrored without any verb opting in: directive→open, response→close, claim→claim, verdict→note, eight-field payload {v, at, from, to, kind, slug, pri, ptr}. A mirror failure never fails the v3 write.
  • Seed (Task 12). obligations <team> --agent <a> --export-open writes one bus-v4 open per slug the old fold says the agent owes AS ASSIGNEE (row assignee is the agent, @agent, *, or a role the agent holds — rows the agent merely sent are not its obligations; ruling a0927018; RULING f9f5823b 2026-09-05: a broadcast, assignee *, is an obligation of EVERY recipient except its owner, so _old_open_set adds open star rows whose owner is not the agent — needs-me never lists them — matching the fold's to == all and from != agent; RULING 13a58789 2026-09-05: broadcast closes are PER-RECIPIENT — the row's single status is the OWNER's disposition, never a recipient's close, so a broadcast stays open for every non-owner until THAT agent acks it (acked_by on the row, or the ack doc at _coord/acks/<slug>/<agent_key>.md); an unreadable ack reads as no ack; RULING 55b1056b 2026-09-06: the OWNER's terminal status (router.TERMINAL_STATUSES) ends a broadcast for EVERYONE — it is open for nobody, on the old set and on the seed — while a recipient's ack still closes it for that recipient only; respond on a broadcast writes the responder's ack record itself. RULING 316ef7ab 2026-09-06: a broadcast's status moves ONLY by its owner — a non-owner's respond records the shard, writes its own ack, and closes only its own fold (the first recipient's answer had been flipping the row to done and, under 55b1056b(1), discharging every other recipient). Only the OWNER's terminal transition mirrors its v4 close to all (the v3 record still goes to the owner): the old plane drops a terminal broadcast for every recipient, so the new plane must close it in every recipient's fold too (measured 2026-09-06 05:03Z: a close addressed to the owner alone left every other fold reading only_new). DUAL-RUN RULE: coord-fold close on a broadcast is half a close — coord-fold stays old-plane-free by design, so pair it with coord-engine inbox <team> --ack <slug> --agent <you> until cutover, or the old plane reads only_old), idempotent via _coord/bus-v4/seeded/<agent>.md (--force re-seeds). A re-seed RECONCILES: every slug open in the agent's coord-fold checkpoint that the correct set no longer contains gets a bus-v4 close (ptr = the seed marker), so a leaked open is retired on the stream rather than deleted (G28); an unreadable checkpoint makes the whole seed UNKNOWN (rc 3), never a silent partial reconcile. Each row the seed would export is CONFIRMED against the doc its pointer names (one pointed read per row, no enumeration; coord-boss 8a280028, 2026-09-06): the needs-me projection lags the doc until reconcile, so a row closed seconds earlier was re-exported open and out-ordered its own close on v4; a terminal doc skips the row (skipped_terminal_doc in the marker), an unreadable doc keeps the projection's answer (over-capture). Refuses on an UNKNOWN old fold — a seed from a partial answer would enshrine the gap as absence. Classified as a WRITE.
  • Comparator (Task 14). compare-to-fold <team> --agent <a>: the old open set vs the coord-fold checkpoint (team/<team>/member/<agent>/fold/checkpoint.json) as (slug, pri, ptr) tuples; prints AGREE n=k or DIVERGE slugs=[…]; appends one JSON line to _coord/bus-v4/compare/<agent>.jsonl. rc 0/2/3 = agree/diverge/ UNKNOWN. A WRITE (it logs).
  • Cutover check (Task 14). cutover-ready <team> --agent <a> exits 0 only when the trailing AGREE run is ≥ --min-run (24) over ≥ --min-hours (24), the open set both grew and shrank within it, the divergence/ recovery drill is recorded at _coord/bus-v4/drill/<agent>.md (G13), and --ship-check-rc 0 carries the rc of the runbook's scripts/ship_check.py fulcra <HEAD> --git <abs> --fulcra-api <abs>. The window flags exist so the operator can compress the window deliberately, never silently. A read.
  • The flip (coord_engine.cutover, 2026-09-06). cutover show <team> / cutover set <team> --serve fold|files --reason … --agent <a> read and write ONE switch document, _coord/bus-v4/cutover.json ({"v":1,"serve":"fold"|"files","at","by","reason"}). needs-me and obligations read it FIRST, before any file-plane work, on every invocation (nothing is cached). Three states: absent → files, today's answer, so the flip cannot happen by accident; unreadable or malformed → UNKNOWN (rc 3) and nothing is consulted — a host that cannot read the switch after the flip must not answer from files and report clean (split-brain; codex-reviewer P0, engine-ship-gate-6445cde8); serve: fold → the agent's coord-fold checkpoint IS the answer and the task index, role resolution and review listing are never invoked (codex-coder P0, same register; sentinel tests prove it); a checkpoint that is absent, unreadable or corrupt is UNKNOWN (rc 3), never CLEAR — an identity that has not seeded its fold does not thereby owe nothing. Under fold, tasks carries every open, directives the non-review ones, reviews the review-request rows, blocks / reminders / role_duties are consulted-and-subsumed (their opens are in the fold), and forge_feedback is served from the forge PROJECTION section of the summaries document by pointed reads only (one document read, one ack read per item, changed_slugs empty so nothing re-lists a feedback directory); a projection that is absent, stale, incomplete or malformed is UNKNOWN, never a raw scan (codex-coder P0, engine-ship-gate-c4a8410a; a list_dir sentinel in the tests proves the fold path never enumerates). The checkpoint's own health survives the serving boundary: unread_events > 0, a non-empty unreadable_pointers, or malformed health fields make both public reads UNKNOWN (rc 3) with the known rows retained as partial data (codex-reviewer P0, same register). Rollback is --serve files, one write, fleet-wide. cutover is MIXED: show is a read, set is activity.
  • Forge projection cost (ruling 30be1f8e, 2026-09-05). build_forge_projection lists the parent _coord/forge/feedback/ ONCE and lists per PR only the PRs that appear there; measured on the live store 125 responsible PRs cost ~77 s of per-PR listings that almost all returned empty, against a sub-second parent listing naming two directories. An EMPTY or FAILED parent listing proves nothing (a listing answers identically for a real empty dir and a bad path) and falls back to the per-PR loop unchanged: the pruning only removes work it has positive evidence for. COORD_FORGE_BUILD_BUDGET (default 300 s, raised from 60 on 2026-09-07) is then a ceiling, not a requirement; the reconciling host carries 180 in its launchd plist.
  • Activity classification. obligations is MIXED: --export-open, --repair-unknown and --seed-checkpoint each write (two of those already did while the verb classified as a read).

Collect browser reconnect

Collect's current availability contract uses a bounded fresh quiet bearer read, never cached positive readiness. Local readability is separate from server/principal/provider/worker success; unknown, pending, missing and transition are distinct and preserve saved credentials. Only explicit authenticated, closed-scope recovery may request UI, followed by quiet confirmation. A missing optional refresh item is compatible with a manual bearer; never promise automatic refresh from it. Pending reads must not spawn duplicate prompts. Keep the existing executable/helper identity and quiet no-fallback policy; native denial causes and grants require their own evidence. Worker scope metadata comes from declared read sites, is checked against the original/current configuration and auth revision, and routes hydration errors to Configure versus shared bearer errors to Fulcra Settings. After restart/stale scope, report UNKNOWN; do not infer authority from traceback wording. Recovery navigation must not enable/run a source or overwrite/delete credentials.

Onboarding and Settings share the browser-link helper and Collect-owned SDK actor. The historical cli_login_start/cli_login_poll route names now speak protocol 2: a durable attempt UUID and captured device-code hash authorize one bounded SDK grant request per poll. No CLI execution, output parsing, or terminal credential adoption occurs. Old unscoped completion/classic requests return 409 before effects; a CLI rc 0 never proves approval. Availability is independent of PATH. Keep authorization-origin/code checks and explicit protocol/success checks together; pending replies alone cannot advance onboarding or reconnect.

Preserve the private auth-attempt journal through restart. It contains hashes/order metadata, never device codes or credentials. New start, paste, signout and cancellation fence stale callbacks; credential commits rotate source epochs under the account-transition gate, which opens only after credentials AND the journal revision commit. Incomplete transitions report unauthenticated/reconnect required. Renewal status updates compare current auth revision/token, so stale failures cannot relabel a newer successful sign-in. A claimed device grant or rotating refresh grant with an unknown outcome requires a fresh sign-in, never an automatic replay. Access/refresh credentials live in Collect's OS Keychain service. Same-account renewal preserves source epochs; manual tokens have no implicit CLI renewal. The prior principal-checked CLI renewal path remains only for pre-upgrade credentials with no committed owned-auth revision, and a newer interactive revision revokes it. Do not remove that compatibility path without a documented fresh-sign-in migration.

Interactive auth journal lease precedes account-transition/config leases. Refresh may already run inside an account-shared caller scope: it MUST use the journal's SQLite-only revision/claim methods, never the interactive auth lease (which may be waiting for account EX). Committed auth revision changes inside account EX; final refresh commit holds account SH plus its SQL transaction. Network requests run outside newly acquired account/config leases; the separate cross-process refresh lease serializes rotating grants. SDK polling loops are not used. Run the auth suites and node --test packages/web-ui/tests/*.test.cjs when changing these paths. Packaged, signed Keychain/restart QA is still required before release; source tests do not establish that evidence.

Daemon CLI SIGTERM must unwind startup and running-loop ownership cleanup. Quiet Keychain helper lifetime is bound to the private-pipe requester; owner death exits the helper itself, never a reused foreign process group. Retain UNKNOWN for interrupted writes and the existing consumed-grant no-replay journal.

Controlled manual backfills may use fulcra-collect run PLUGIN --timeout-seconds N (integer 1–7200). The ordinary scheduled budget and shared in-flight guard remain unchanged. Keep the captured full source scope until its original pending batches reconcile; restoring a live range cannot credit earlier historical coverage or silently rebind pending work.

Collect shutdown closes scheduled-worker admission at the Popen/registration boundary and retains accepted launch threads until their owned children are terminated and reaped. Cancellation remains a shutdown condition, not source success. Keep process-group identity reserved through TERM/KILL, and never signal a reaped process identity. Trakt status and hydration sample one tuple per operation; retain physical bundle/legacy error origin through worker validation. Absent-bundle legacy denial routes to explicit reconnect, not bundle authorization or per-field grants. Current bundle denial permits one grant; pending/changed access permits quiet recheck only. Do not widen logical credential write routes to accept the physical bundle key.

Fresh Collect account and Trakt bundle credential reads share the same uncached boundary and may recheck pending availability quietly at most three times within 15 seconds, reserving the complete existing native wait before another observation. No cached value is accepted; the original credential revision must remain current before and after each attempt. Do not treat this as approval, renewal-grant or mutation replay. Denied/changed reads stop and exhausted pending reads remain UNKNOWN.

Apple Podcasts libraries can omit cleaned-title and duration columns. Both import and health use the same closed schema adaptation. Unknown duration stays null in source metadata and produces a point Event at the known last-played timestamp, without inventing elapsed listening time; stable source identity is unchanged.

A missing Podcast duration must not erase a previously verified interval for the same primary play and endpoint. Preserve its known duration; reject conflicting/malformed prior timing. A prior guessed interval with null source duration is not authoritative. Preserve raw source snapshots and distinguish their fields from canonical retained enrichment.

Development media chunk planning retains prior unindexed rows only when their source identities intersect the current chunk. This preserves cross-chunk aliases and twins while avoiding repeated policy reads over unrelated earlier history; current candidates and relevant aliases still receive fresh exclusion checks.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.