Vstup do repozitáře: co je automatické, co dekorativní a kde se to láme

Forenzní zjištění, změřené 2026-09-10 proti origin/master při merge PR #147, v primárním checkoutu a v jednom linked worktree. Odpovídá na jedinou otázku: když do tohoto repozitáře vstoupí člověk nebo agent, co zkonverguje samo — sestavený spustitelný soubor, běžící sdílený server, připojená relace, peer na nástěnce, načtené pokračování — a co stále čeká, až si někdo vzpomene na příkaz.

Cíl, proti němuž se měří, je invariant, který tomuto repozitáři předložil balík promptů (balík „automatic control plane“, SPEC.md): vstup do povoleného repozitáře nebo start podporované relace agenta konverguje, idempotentně a v omezeném čase, k jednomu zdravému místnímu serveru, dohledatelným povrchům, připojené relaci, přítomnosti peerů a načtené kontinuitě, bez ručního startu či připojení. Každý nález níže uvádí soubor a řádek, z něhož byl přečten, a příkaz, který ho ukáže znovu. Nic zde není číslo, které repozitář umí spočítat; kde na čísle záleží, uvádí se místo něj příkaz, který ho spočítá.

Slovník

Balíček mluví vlastním jazykem. Tento repozitář už má slova pro většinu z něj (CONCEPTS.md) a tento dokument používá slova repozitáře.

Cesta od vstupu ke spolupráci, tak jak je

flowchart TD
  cd["cd &lt;repo&gt;<br>direnv → .envrc → bin/majordomus-env<br>→ majordomus env export --banner --bridge<br>exports MAJORDOMUS_ROOT/SHARE/COMPLETION_BIN,<br>and MAJORDOMUS_URL only if a lease exists<br>one TCP connect to the lease's address,<br>no HTTP, no version, no identity<br>never builds, never starts anything<br>.envrc:33, src/environment/shell.rs:116-130"]
  agent["agent starts<br>Claude Code fires SessionStart<br>→ .claude/hooks/majordomus-session-start<br>→ majordomus capture session --event start<br>→ session start --if-open keep<br>→ briefing on stdout (episode, task,<br>blockers, handover Next Action)<br>no peer board, no server, no announce<br>lib/capture.sh:797-816"]
  mcp["MCP client attaches<br>.mcp.json → bin/majordomus-mcp<br>→ majordomus mcp → lease::elect<br>first process serves (lease + loopback HTTP),<br>later ones bridge<br>the only thing that starts the server<br>src/commands/mcp.rs:135, src/lease.rs:89"]
  peer["peer on the board<br>attach on initialize, named p&lt;n&gt;;<br>announce is a tool call the model<br>may or may not make<br>in memory, gone with the process<br>src/peers.rs:268, :315"]
  context["context loaded<br>majordomus context when somebody runs it;<br>the briefing carried the handover already"]
  cd --> agent
  agent --> mcp
  mcp --> peer
  peer --> context

Co je dnes skutečně automatické: spustitelný soubor sestaví první launcher, který jej potřebuje (bin/majordomus-cli:36-56); první klient MCP spustí server a každý další se připojí (ADR 0003); startovací událost poskytovatele otevře epizodu a předá modelu další akci poslední předávky (ADR 0015, ADR 0017); zastaralé lease každého tvaru je převzato (project.shared-server-resilience); nahrazený spustitelný soubor ztrácí své lease (tests/shared_units.rs:147).

Co není: při vstupu nic nezajišťuje server; shell ani agent bez MCP žádný nedostane; linked worktree dostane vlastní server a nikdy nevidí server repozitáře; dvě relace v jednom checkoutu sdílejí jednu epizodu; nástěnka při restartu zapomene všechno a nikdy nic nevyprší; žádná plocha neukazuje vlastní stav serveru; jediný příkaz, který má každý worker spustit jako první, zahynul na mlčícím peeru.

Hlavní příčiny, seřazeno

P0 — invariant nemůže platit, dokud toto stojí

1. Jeden server na checkout, ne na repozitář. Lease žije v kořeni checkoutu (src/lease.rs:63-65), kořenem je nejbližší .ai/manifest.yaml (src/repository.rs:146-160), každý worktree jeden má a identita, kterou sonda porovnává, je digest toho kořene (src/repository.rs:256-261, src/lease.rs:264). Linked worktree si tedy zvolí vlastní server na vlastním portu s vlastní nástěnkou a záložní odkaz context na lease primárního (lib/context.sh:344-353) čte nástěnku, která patří jinému checkoutu, jehož peeři nenesou pole worktree. ADR 0003, CLAUDE.md i docs/MCP.md:50 říkají „na repozitář“. Scénář worktree v balíku nesele; je nedosažitelný. Reprodukce: v linked worktree, zatímco primární obsluhuje, bin/majordomus-cli env status --format json | jq '.services[0].availability'.

2. Entry nic nezajišťuje. .envrc sleduje lease a vyhodnotí jeden export (.envrc:24, :33); bin/majordomus-env nikdy nebuilduje (bin/majordomus-env:31-50); shim SessionStart otevře epizodu a nedotkne se žádného serveru (lib/capture.sh:797-816). Server existuje, až když klient MCP spustí bin/majordomus-mcp. Shell člověka, relace Codex nebo Gemini bez adaptéru životního cyklu nebo relace Claude, jejíž handshake MCP selhal, všechny vstupují do repozitáře, který nemá server, a nic jim to neřekne. MAJORDOMUS_URL prostě chybí (src/environment/shell.rs:116-130). Reprodukce: bez lease, bin/majordomus-env export --shell direnv | grep -c URL. Uvedení provideři jsou příklady těch, kteří adaptér životního cyklu nesou, a těch, kteří ne; který je který, není seznam, který tento dokument vede — je to docs/generated/providers.md, zapsané z share/providers.yaml příkazem majordomus generate providers (ADR 0024).

3. Epizoda je jedna na checkout, klíčovaná na ničem, co provider poslal. session start --if-open keep vrací otevřenou epizodu bez ohledu na to, co říká --provider-session (lib/session.sh:157-165); záznam nemá pole providera, do kterého by se zapisovalo (share/allow/session.txt), takže continuity.state.provider je deklarováno a nikdy neprodukováno (src/capability/builtin/continuity.rs:157-159, :476); událost konce z libovolné relace uzavře epizodu pro všechny (lib/capture.sh:860-884). Sedm souběžných relací změřených 2026-09-09 mělo mezi sebou jeden záznam. „Relace se registruje automaticky“ z balíčku je pravda pro první relaci a tiše nepravda pro každou další. Reprodukce: pošlete dva payloady SessionStart s různými hodnotami session_id přes .claude/hooks/majordomus-session-start ve fixture, poté majordomus session.

4. Přítomnost je paměť procesu bez vypršení a nudge k opětovnému připojení nikdy nepřijde. Nástěnka umírá se serverem (src/peers.rs:4-12); v běžné cestě vlastníka majordomus mcp nic nevolá reap(), takže mrtvý HTTP peer zůstává attached: true, dokud vlastník neodejde (src/shared.rs:27-71 nemá žádného sběrače; src/commands/serve.rs:71-75 je jediná smyčka, která ho má); oznámení nikdy nevyprší (src/peers.rs:127-135); při failoveru mostu se odpověď reinitialize — instrukce, které říkají „ještě jste nic neohlásili“ — zahodí (src/mcp/bridge.rs:205-221), takže přesný incident, který src/mcp/protocol.rs:331-343 cituje, je na cestě, kde se stal, neopraven. Žurnál rozpracovaný na feature/peer-board-survives-restart (ADR 0034, přidělené na nástěnce, v době psaní nepushnuté) odpovídá na polovinu restartu a na nic dalšího. Od té doby: vlastní čtenář serveru sbírá vypršelé relace na každé cestě a most po opětovném připojení přehraje poslední přijaté oznámení svého klienta a po převzetí ho přenese na vlastní nástěnku (fáze 03, na této větvi); vypršení u oznámení a epizoda na relaci poskytovatele zůstávají (fáze 04). Reprodukce: curl -s "$MAJORDOMUS_URL/api/v1/peers" | jq '.peers[] | {id, attached, last_seen_seconds_ago}' poté, co byl přemostěný klient zabit pomocí SIGKILL.

5. Vlastní stav serveru je na disku a na žádném povrchu a „ready“ má tři definice. Lease nese pid, url, started_at a identitu spustitelného souboru (src/lease.rs:281-291) a žádná schopnost ji nečte (grep -rn lease apps/majordomus-cli/src/capability/ je prázdné). health.report počítá peery a o procesu neříká nic jiného (src/capability/builtin/health.rs:416-420). Připravenost rozhodují nezávisle Served::ready (výstup producenta existuje, src/http/surfaces.rs:152-159), health.ready (capabilities > 0, health.rs:480-486) a holé TCP spojení env (src/environment/probe.rs:74-89); sonda lease používá čtvrtou otázku, GET / plus digest identity (src/lease.rs:257-268), a žádná se neptá na verzi. Ve spustitelném souboru pro server neexistuje status, ensure, stop ani explain (src/cli.rs:31-71) a doctor shellového nástroje neví, že lease existuje (grep -n mcp lib/doctor.sh). Od té doby: lease je jeden typ čtený jednou a server.status jej servíruje, s serve status/ensure/stop na spustitelném souboru (etapa 02, 03); health.report nese kontrolu server rozhodnutou týmž čtením, takže zpráva jmenuje adresu, verzi a zda to, co odpovídá, je kód na disku, a zastaralý lease je zjištění, nikoli mlčení (etapa 09, apps/majordomus-cli/tests/health_server.rs). Odpovědi o připravenosti jsou pojmenovány, ne sloučeny: čtyři otázky o čtyřech subjektech, každá ukázaná na svého vlastníka v docs/MCP.md („Four readings of „ready““) a v dokumentaci modulu, kde se těch čtyři setkávají (src/capability/builtin/health.rs). doctor shellového nástroje stále neví, že lease existuje. Reprodukce: bin/majordomus-cli --help | grep -c -E 'status|ensure|stop'; curl -s "$MAJORDOMUS_URL/api/v1/health" | jq '.checks[] | select(.id=="server")'.

P1 — invariant platí jen náhodou nebo jen pro jednu relaci

6. majordomus context skončil bez jediného slova, kdykoli nejnovější peer na nástěnce neohlásil nic. Holé [ -n "$pscope" ] && bylo posledním příkazem smyčky výpisu (lib/context.sh:398 před opravou); pod set -e byl jeho stav stavem pipeline a příkaz skončil kódem 1 bez čehokoli na obou proudech. Případ pokrývající sekci nikdy nedal tichého peera na konec (test/cases/106_context_peers.sh). Opraveno na fix/context-survives-a-silent-peer, případ rozšířen. Reprodukce (před opravou): připojte druhého klienta MCP, který nic neohlásí, pak majordomus context; echo $?.

7. Bootstrap jmenuje příkazy, které se nevyřeší. .envrc:20 dává na cestu jen bin/, takže majordomus je shellový nástroj; AGENTS.md a CLAUDE.md říkají každému workeru, aby spustil majordomus worktree, majordomus generate, majordomus mcp a docs/ENVIRONMENT.md:8 říká majordomus env a každý končí s 2 a přesměrováním na bin/majordomus-cli (bin/majordomus:87-105, :133-143). Oba bootstrapy se generují z .ai/repo/policy.yaml, takže oprava je jedna šablona. Reprodukce: majordomus worktree; echo $?.

8. Volba má tři souběhy, které lease nevidí. take_over odstraní soubor bezpodmínečně po klasifikaci, která už je stará (src/lease.rs:243-254); převzetí superseded nechá starý proces obsluhovat na jeho socketu vedle nového (src/lease.rs:227-229, src/http/server.rs:77-86); server, jehož lease byl převzat, stále drží HELD a jeho obsluha signálu odlinkuje lease aktuálního serveru při SIGTERM (src/lease.rs:319, :383-397, přečteno, nereprodukováno); a patnáctivteřinová lhůta pro bind začíná před App::load, takže studený start pomalejší než ta lhůta způsobí, že čekající peer prohlásí vítěze za opuštěného (src/commands/mcp.rs:169, src/lease.rs:130). Dva klienti naráz jsou otestováni (tests/mcp_shared.rs:939); tři ne; cesta timeoutu při připojení nemá test vůbec. Reprodukce: grep -n JOIN_TIMEOUT apps/majordomus-cli/tests/*.rs (prázdné).

9. Dva systémy claimů, které se nikdy nepotkají. Oznámený rozsah peera žije na nástěnce; rozsah úlohy žije v current.yaml napříč worktrees; check --overlap čte jen druhý (lib/start.sh:84-97), peers.announce zapisuje jen první (src/capability/builtin/peers.rs:117); jediné místo, kde se kříží, je sekce peers v context, která je poradní, za šesti podmínek se sama vypíná (lib/context.sh:348-370) a nedokáže odlišit čtenáře od peerů. CONCEPTS.md:16 definuje „claim“ jako první a docs/MCP.md:109 jej používá pro druhý. Reprodukce: majordomus check --overlap, zatímco peer oznámil váš rozsah.

10. Automatická cesta není to, co testy spouští. Případ 90 vyvolá samotný launcher s --http-port 0 a ručně psanými rámci; žádný test nenechá klienta přečíst .mcp.json ani nenaváže zdokumentovaný výchozí port (test/cases/90_mcp_shared_server.sh:31-60); .envrc se kontroluje jako text (test/cases/100_environment.sh:24-57); sekce peerů je prokázána proti python stubu (106:38-53); scripts/cockpit-probe:49-84 měří jakýkoli server, který klient už spustil; tvrzení mcp-lease-resilience jmenuje případ, který dokazuje jednu větu z pěti (docs/CLAIMS.yaml:896, 90:107-114); případ užití serve-the-layer-to-ai-clients nese čtyři tvrzení MCP a jeho scénář nespouští žádný server; project.shared-server-resilience jmenuje úlohy CI test a pages, které validate.yml nemá. Sada na úrovni crate je silná na pády (tests/mcp_shared.rs:645, :695, :734, :910) a přeskakuje se u změny, která jen vybírá rust-integration (scripts/rust-check:52). Reprodukce: grep -rn "8741" apps/majordomus-cli/tests test/cases.

11. Cockpit neukazuje žádné peery, žádné relace mimo tento checkout a skrývá dvě vlastní oblasti. peers.list nemá stránku, položku navigace ani oblast (grep -n peer apps/majordomus-cli/src/cockpit/*.rs); continuity je jeden worktree, jedna větev; navigace vrací méně oblastí, než deklaruje její vlastní doc komentář, takže /cockpit/executions a /cockpit/quality odpovídají, ale nelze se k nim dostat a jsou mimo kontrolu sond, která prochází navigaci (src/cockpit/nav.rs:7-11 proti :85-154, scripts/cockpit-probe:101-105); seznam stránek v tests/cockpit.rs:14-45 a tabulka rout v docs/COCKPIT.md:41-60 jsou vedeny ručně a zaostávají. Reprodukce: curl -s "$MAJORDOMUS_URL/cockpit" | grep -c '/cockpit/executions'.

12. Živý kanál nese provádění a nic jiného. Obálka je typovaná a přehratelná (src/execution/event.rs:31-47, src/http/events.rs:236-270) a jedinými publikátory jsou úložiště provádění a sink handleru; připojení peera, předání lease nebo přechod zdraví je řádek v logu (src/http/mcp.rs:153, :168, :187). Cockpit dotazuje worktrees a aktivitu (share/cockpit/worktrees.js:4, activity.js:2). Reprodukce: curl -s "$MAJORDOMUS_URL/api/v1/executions/protocol" | jq '.events[].type'.

P2 — drift a duplicita, které opravu pokousají

13. Lease se parsuje ručně na čtyřech místech bez typu Lease: src/lease.rs:204-240, :73-78, src/environment/services.rs:120-131, lib/context.sh:356 (jq), .just/serve.just:19 (sed, což se rozbije v den, kdy se soubor zformátuje).
14. docs/MCP.md:32 říká, že server nespouští nic než klient; serve ano (src/commands/serve.rs:53-62) a na terminálu běží donekonečna bez klienta (:70-76). ADR 0003 říká, že Swagger UI je na /docs; je na /swagger (src/http/swagger.rs:35). Převzetí superseded je zdokumentováno v komentáři kódu a unit testu a v žádném dokumentu. docs/WEB.md:30-40 vynechává /events, přestože tvrdí, že nic v jeho tabulce není typováno dvakrát. docs/ENVIRONMENT.md:59 vynechává --bridge a :74-75 jmenuje .just/env.just, které neexistuje; just env existuje jen v nesledovaném generovaném mostu. lib/capture.sh:709-711 říká, že událost start nezapisuje nic na stdout; :784-796 říká opak a je to, co běží.
15. Fakta zapsaná dvakrát: cesta lease v osmi souborech; výchozí port na stránkách tvrzení a v docs/MCP.md; skládání cesty spustitelného souboru v justfile:28-29 a lib/rust_bin.sh:52-66; sdílený adresář v justfile:32 a lib/rust_bin.sh:105; jméno poskytovatele a klíče jeho payloadu ve dvou tabulkách adaptérů (lib/capture.sh:108, :137) a čtyřech shimech; výchozí build profil v pěti souborech. Seznam k udržování je docs/HARDCODING_LEDGER.yaml; tyto řádky v něm nejsou.
16. doctor se nikdy nezastaví na nálezu (lib/doctrine.sh:153-163, lib/common.sh:35) a běží nad svůj rozpočet (MJ_TIMING=1 majordomus doctor); varování o nepushnuté větvi je holé mj_warn mimo registr doktríny (lib/doctor.sh:349).
17. Otisk workflow nepokrývá generovaný most (src/environment/resolve.rs:596-615) a .envrc nesleduje spustitelný soubor, takže build po vstupu nic nezmění, dokud se nezmění lease.

Matice auditu

Graf závislostí

flowchart TD
  a["A identity: one repository, every server of it<br>(the git repository named beside the checkout;<br>the servers of one listed from any of them)"]
  b["B the server's state as one typed value<br>(lease read once by a Lease type; status,<br>version, executable, peers, readiness on<br>every surface)"]
  c["C ensure: entry converges<br>(the start event and the MCP launcher<br>call it; a shell is told, not served;<br>bounded, idempotent, concurrency-safe)"]
  d["D episode keyed on the provider's session<br>(one record per session, ended by its owner)"]
  e["E presence: expiry, reaper, reconnect nudge,<br>claims with a lease (journal from ADR 0034)"]
  f["F events for peers, lease, health<br>on the existing typed channel"]
  g["G Cockpit: peers, sessions, server state"]
  h["H gates: cold start through the configured path,<br>storm, crash, two worktrees, two providers,<br>drift; rule + ADR; docs"]
  a --> c
  b --> c
  c --> f
  f --> g

D, E a H záměrně nenesou hranu. Kresba, kterou toto nahradilo, vedla od C jedinou svislou kolejnici a dotýkala se jí D, F i G, což se čte jako C → D; odstavec níže říká opak a uvádí důvod — D „je nezávislé na A–C a blokuje relace se automaticky registrují balíčku samo o sobě“. Kolejnice byla prvek rozvržení, ne závislost, a přežívá věta s odůvodněním.

A musí přistát první: každý další krok, který říká „repozitář“, myslí git repozitář, a dnes kód myslí checkout. ADR 0035 bere A a B: volba zůstává na checkout, protože server obsluhuje vrstvu checkoutu, v němž byl spuštěn, a to, co chybělo — aby se servery jednoho repozitáře daly odlišit od serverů dvou a vypsat z kteréhokoli z nich — řeší indexová routa a server.status. B před C: ensure hlásí stav, ke kterému zkonvergoval, takže stav musí mít napřed typ. D je nezávislé na A–C a samo blokuje „relace se registruje automaticky“ z balíčku. E závisí na větvi žurnálu nebo ji nahrazuje a nesmí se stavět dvakrát. F, G, H následují.

Starý kód ke smazání nebo sloučení a vlastníci k zachování

Smazat nebo sloučit:

• čtyři ruční parsery lease (položka 13): u tří spustitelných souborů hotovo díky LeaseFile::read a dva čtenáři v shellu zůstávají do fáze 09 — v 534e8fb7bc se přesunuli na serve status a scripts/ci/lease-reader-check hlásí jednoho čtenáře;
• vlastní čtečka lease lib/context.sh (přesunutá v 534e8fb7bc) a její načítání nástěnky, jakmile spustitelný soubor nástěnku hlásí a shellový nástroj se ptá jej — jedna čtečka, ne dvě.
• .just/serve.just:12-20 (mcp-status, open) parsující lease pomocí sed; recepty zůstávají a volají příkaz stavu.
• čtyři nezávislé odpovědi o připravenosti (P0 položka 5); jedna zůstává a ostatní ji volají.
• služby environment se testují jako holé TCP spojení, jakmile bude existovat typovaný stav.
• systém nároků jen s oznámeními, nebo ten jen s rozsahem úlohy — ne oba; rozsah úlohy je trvalá, vynucovaná forma (.ai/repo/features/coordination.md), takže nástěnka by měla nést ji, a ne druhou.

Zachovat a stavět na tom:

• volba jedním atomickým vytvořením a lease každého převzatého tvaru (project.shared-server-resilience) a jeho sady testů;
• snapshot prostředí jako jedna hodnota, kterou vykresluje každý povrch (project.envrc-is-an-adapter); ensure je jeho spotřebitel, ne soupeř;
• provider, který vede hranici epizody, a odvozený briefing (ADR 0015, ADR 0017);
• provádění jako typovaný kanál událostí (ADR 0033) — peeři a lease na něm publikují, nedostávají druhý socket;
• registr schopností jako jediné místo, kde se deklaruje povrch (ADR 0002, ADR 0004).

Odmítnuto a proč

• Server spuštěný na cd. project.envrc-is-an-adapter zakazuje vstupnímu hooku cokoli spouštět a ADR 0003 odmítá daemon: bez klienta není proces. Shell není klient. Vstup shellem hlásí stav a pojmenuje příkaz; vstup agentem (startovní událost poskytovatele, MCP launcher) konverguje, protože klient přichází.
• Kontrola zdraví jen podle PID. Již odmítnuto pravidlem tests/shared_units.rs:142-146; zůstává odmítnuto.
• Druhý event socket pro peery. Existuje jeden typovaný kanál; nový rozsah na něm je rozšíření protokolu, ne nový transport.
• Porty na více místech. src/cli.rs:898 je jediná deklarace; dokumenty, které ji opakují, jsou projekce k regeneraci, ne fakta k uchování.

Plán, namapovaný na fáze balíčku

Co tento audit neověřil

• Souběh v obsluze signálu (položka 8, třetí klauzule) byl přečten, nikoli reprodukován.
• feature/peer-board-survives-restart bylo přečteno ze svého worktree, necommitnuté; to, co přistane, se může lišit.
• Čas vstupu byl měřen za tepla, na jednom stroji, třikrát; bench je nástroj pro tvrzení.