robisie 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Historia zmian klienta / Client changelog
+
+## 0.1.1 (2026-10-30)
+
+Wydanie utrzymaniowe: bezpieczniejsza instalacja, odzyskiwanie i diagnostyka oraz biblioteki klienta. Poniższe 45 kart ma odbiór **TAK lokalnie**; sprawdzenie wersji z rejestru npm pozostaje osobną bramką. / Maintenance release: safer installation, recovery and diagnostics, plus client libraries. The following 45 cards have **local acceptance**; verification of the npm registry release remains a separate gate.
+
+### E3
+
+- `10393507` — init i doctor uwzględniają wersję kontraktu każdej odpowiedzi.
+- `13bafb12` — odbiorca klienta ustala dokładny kandydat do sprawdzenia.
+- `18235645` — paczka wybiera rozłączne zakresy równoległych kart.
+- `2e9242da` — klient rozróżnia awarię CI i błąd kodu z dostarczonych wyników.
+- `4316e68e` — recenzent klienta czyta raport związany z kartą i kandydatem.
+- `5084ba5e` — uninstall zachowuje rolę, gdy brakuje jej oryginału w kopii.
+- `59255cbe` — doctor wykrywa brak instrukcji uruchomienia zainstalowanych ról.
+- `695e6eed` — klient sprawdza komplet lokalnego pakietu bez skryptu hosta.
+- `737bbf62` — reguły intencji klienta używają ról jego instancji.
+- `78225362` — uninstall zachowuje manifest do zakończenia sprzątania.
+- `79f7e41f` — doctor sprawdza kontekst projektu używany przez pomocnik klienta.
+- `80931e36` — init zachowuje działający profil logowania Bash.
+- `8d297c6f` — niepełny ostatni werdykt nie odziedzicza wcześniejszego PASS.
+- `945c44b9` — init sprawdza odczyt wszystkich docelowych plików przed pierwszym zapisem.
+- `9d10bca2` — paczka odtwarza aktywne zadania z zachowanej tożsamości.
+- `a6e291b6` — instalacja odmawia względnych katalogów konfiguracji.
+- `af3a5bc3` — init odrzuca znane konflikty konfiguracji przed zapisaniem instalacji.
+- `b9402172` — klient rozpoznaje rzeczywiście odebrane zależności karty.
+- `bb29afd9` — klient API tworzy pierwszy tor i szkic karty.
+- `da4ddc8e` — konsument TypeScript korzysta z typów zainstalowanej paczki.
+- `dcf3218b` — doctor potwierdza pełny start pomocnika przed uznaniem go za sprawnego.
+- `dd86b397` — paczka wiąże dowód startu z właściwą próbą zadania.
+- `e65b667c` — uszkodzona ewidencja instalacji odmawia przed zmianą plików.
+- `fb07c02f` — klient zachowuje decyzję odzyskania pracy po restarcie.
+- `ff361096` — odczyt karty z API paczki zachowuje indeks jej pełnych danych.
+- `ff998946` — klient odczytuje pełną odpowiedź selektora bez importu hosta.
+
+### E4
+
+- `b231a265` — obcy agent uruchamia przykład konfiguracji silnika z paczki.
+- `c781f9f0` — agent korzysta z API paczki bez zgadywania odczytu i ponowienia.
+- `deb1e7d2` — doctor odróżnia niedostępny plik instalacji od braku klucza.
+- `805aad70` — Operator B podłącza paczkę bez klucza w argumentach i bez kasowania cudzego MCP.
+
+### E5
+
+- `0b0940cc` — powrót klienta przechodzi przez dwa rzeczywiste archiwa paczki.
+- `5e579f94` — ponowne pakowanie usuwa wycofane artefakty klienta.
+- `6964272e` — notatka wydania odpowiada faktycznej zawartości klienta.
+
+### E6
+
+- `1bd3a86d` — niepełny zagnieżdżony blok nie usuwa cudzych instrukcji.
+- `31a377ef` — init przywraca prywatność własnego katalogu instalacji.
+- `3b250acb` — kopie konfiguracji klienta pozostają w prywatnym katalogu.
+- `58a45de0` — eksport sesji klienta nie interpretuje identyfikatora jako polecenia.
+- `5b8dd7f5` — ponowny init przywraca ochronę prywatnej konfiguracji bez zmiany jej treści.
+- `6fddbaec` — init nie przekazuje poświadczenia pod adres z przekierowania.
+- `8b9882ba` — błąd połączenia klienta nie kopiuje sekretu do diagnostyki.
+- `ac688abb` — role planowania i recenzji OpenCode nie dostają powłoki ani edycji.
+- `ad251014` — nieudany proces Codex nie przenosi stderr ani cause do wyjątku klienta.
+- `af5c973c` — odmowa pomocnika nie przenosi jego sekretów do doctor.
+- `ccf5a385` — parser konfiguracji paczki nie powiela obcej wartości w błędzie.
+- `e5413393` — instalator nie zamienia cudzych bajtów konfiguracji na znaki zastępcze.
+
+Ograniczenia odbioru: `805aad70` — krok 5 z rolami i pomocnikami w prawdziwej sesji Claude Code pozostaje niesprawdzony; `80931e36` — profil Bash sprawdzono z symulacją macOS na Linuksie, rzeczywisty przebieg na Macu pozostaje otwarty. `9d10bca2` i `13bafb12` potwierdzają konsumenta paczki; integracja z usługą klienta wymaga osobnego odbioru. / Acceptance limits: the real Claude Code session for step 5 of `805aad70` and the real Mac Bash run for `80931e36` remain unverified. `9d10bca2` and `13bafb12` establish package consumer behavior; customer service integration needs separate acceptance.
+
+Pełny opis, wymagania i granice: [notatka PL/EN 0.1.1](docs/RELEASE-0.1.1.md). / Requirements, behavior and limits: [0.1.1 PL/EN release note](docs/RELEASE-0.1.1.md).
+
+## 0.1.0
+
+Kandydat pierwszego wydania, bez daty publikacji. / First release candidate, no publication date.
+
+- `init`, `doctor`, `uninstall` dla Claude Code, Codex CLI i OpenCode; role CEO, Builder i Quality Officer.
+- Pomocniki `client-launch-context` i `ceo-client-launcher` dostarczane w paczce, polecenia przypięte do wersji klienta.
+- Po zgodzie na kartę `ready`: CEO → `ceo-client-launcher` → `spawn_builder`; ręczny start wyłącznie z wyboru operatora. / After approval of a `ready` card, the CEO starts the Builder through the launcher; manual startup is the operator's explicit choice.
+- Biblioteki ESM: `engine-config`, `role-results`, `planer-client`, rejestr ról, walidacja zasiewu/reguły intencji, wybór/zakres, ruchy/odzyskiwanie, tożsamość prób/testera, środowisko Workera, źródła recenzji, wyniki CI i adaptery Claude/Codex/OpenCode z eksportem sesji. Konfiguracja instancji w `robisie.config.json`; wykaz i przykład w [notatce PL/EN](docs/RELEASE-0.1.0.md), SDK w [API silnika](docs/ENGINE-API.md). / ESM configuration, role outcomes, board SDK and engine support libraries are shipped; imports and helpers do not prove a running engine or an autonomous loop.
+- Instalator nie startuje tła/Buildera; doctor nie dowodzi dostępności narzędzi u dostawcy. Claude Code wymaga niezależnej recenzji, verified receipt i odbioru; OpenCode zostaje w `in_review`, Codex wymaga integracji Agent. / Installation and doctor do not establish provider capabilities or acceptance: independent review, verified receipt and operator acceptance remain required; OpenCode stops at `in_review`, Codex needs Agent integration.
+- Wymagania 0.1: macOS/Linux, Node >=20; wsparcie Windows/WSL niezweryfikowane. / Requirements: macOS/Linux, Node >=20; Windows/WSL support is unverified.
+- Kontrakt serwera 1.x (obecnie 1.0.0); odmowa innego major przed zapisem konfiguracji.
+- Ochrona obcych ustawień i instrukcji, pierwsze kopie zapasowe oraz przywracanie własnych plików po uninstall; zmienione role pozostają z ostrzeżeniem.
+- Zapisywanie dostawcy dla każdej roli i diagnoza ograniczeń; bieżąca pętla wymaga jednego dostawcy dla wszystkich trzech ról.
+- Notatka PL/EN i lokalna próba reinstalacji 0.1.0 → syntetyczne 0.1.1 → 0.1.0; to nie rollback opublikowanych wydań.
+
+Pochodzenie klienta: [PR #209](https://github.com/chuppa12/robisie-app/pull/209),
+[merge a41b04ee7961f16e74dbf3a88b5a8199c5339f41](https://github.com/chuppa12/robisie-app/commit/a41b04ee7961f16e74dbf3a88b5a8199c5339f41),
+[ochrona kopii 5ec7cde32a926c593f46e5fb2c86c79fe31bf332](https://github.com/chuppa12/robisie-app/commit/5ec7cde32a926c593f46e5fb2c86c79fe31bf332),
+[bezpieczny zapis b15d73ff2f9f1f1b26de7041ec0623d69d37d347](https://github.com/chuppa12/robisie-app/commit/b15d73ff2f9f1f1b26de7041ec0623d69d37d347),
+[pomocniki i uninstall 36e7e39ed22339a29f851f08c9307d452554981f](https://github.com/chuppa12/robisie-app/commit/36e7e39ed22339a29f851f08c9307d452554981f).

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# robisie 0.1.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Przewodniki: [PL — konto → odbiór → odinstalowanie](https://unpkg.com/robisie/docs/README.md) · [EN — account → acceptance → uninstall](https://unpkg.com/robisie/docs/README.en.md). Przygotuj Node.js 20+, npm, program jednego dostawcy AI oraz pusty katalog; strona i package.json nie są potrzebne. Zacznij od konta i projektu w panelu. Projekt w panelu i katalog na dysku to osobne rzeczy; CEO wymaga dokładnie jednego projektu z discovery.
+
+## Przed init — konto i pierwszy projekt
+
+Załóż konto i zaloguj się w https://robisie.app. Ekran „Zakładamy Twój projekt…” oznacza przygotowywanie projektu; poczekaj na „Twój projekt jest gotowy”. Ten ekran nie dowodzi dokładnie jednego projektu. Nie ma gwarantowanego czasu oczekiwania. Jeśli widzisz „To się przeciąga…”, wybierz „Sprawdź tablicę”: https://robisie.app/dashboard/plugins/planer.
+
+Na liście projektów, tylko gdy nie masz przygotowanego projektu, wpisz nazwę w „Nazwa projektu (np. robisie)” i wybierz „Załóż projekt”. Nie twórz drugiego projektu, jeśli pierwszy już jest przygotowany.
+
+Jeśli trasa przekierowała na /dashboard bez Planera, znajdź „Zacznij od pierwszego projektu”, wpisz „Nazwa projektu” i wybierz „Stwórz projekt”. Również tutaj twórz projekt tylko wtedy, gdy nie masz jeszcze przygotowanego projektu. Potem przejdź do Connect.
+
+## Init — połącz agenta
+
+Człowiek generuje klucz worker z etykietą w https://robisie.app/dashboard/connect i podaje go poza rozmową do ukrytego pytania init, nigdy do czatu, argumentu polecenia ani historii powłoki. W zsh/bash usuń stary ENV, a po udanym init wczytaj zapisany klucz do bieżącej powłoki bez wyświetlania go — init nie ustawia jej środowiska. Dla nowej instalacji z Claude:
+
+```sh
+npm i robisie
+unset ROBISIE_KEY
+npx robisie init --agent claude
+[ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
+npx robisie doctor
+```
+
+Dla Codex lub OpenCode zastąp `claude` przez `codex` lub `opencode`. Sam `--agent` nie usuwa wcześniejszej mapy ról: przy wcześniejszej konfiguracji użyj pełnej mapy z sekcji init w przewodniku. Nowy terminal wymaga obsługi profilu zsh/bash bez `--no-shell`; w innych sesjach wczytaj środowisko zgodnie z przewodnikiem. Agenta uruchom z katalogu instalacji; szczegóły startu ról, pomocników i diagnozy są w przewodnikach PL/EN powyżej.
+
+## Po init — sprawdź gotowość CEO
+
+Po Connect, init i wczytaniu klucza według bloku powyżej uruchom `npx robisie doctor`. Discovery to odczyt aktywnych projektów przez `list_projects`. Nie wymaga wpisywania UUID. Sam `init` z exit 0 ani „połączono” nie wystarczają do potwierdzenia gotowości CEO.
+
+- **0 projektów, exit 1:** `CEO wymaga dokładnie 1 projektu (projektów: 0).` Następny krok: `Sprawdź gotowość projektu na https://robisie.app/dashboard/plugins/planer.` Wróć do przygotowania projektu opisanego przed init.
+- **Więcej niż 1 projekt, exit 1** (np. `CEO wymaga dokładnie 1 projektu (projektów: 2).`): `Uporządkuj widoczność projektów w discovery do 1; sam wybór projektu w panelu nie zmienia discovery.` Człowiek sam decyduje, który projekt zachować aktywny; przy pozostałych na liście wybiera „Archiwizuj”. „Archiwum” → „Przywróć” cofa archiwizację. Nie usuwaj projektów. Kliknięcie projektu nie zawęża discovery.
+- **1 projekt:** oczekuj dokładnie `✓ Połączenie działa: klucz otwiera tablicę (projektów: 1).` oraz końcowego `Wszystko działa. Uruchom swojego agenta i poproś o rolę robisie CEO.` i exit 0.
+
+Po zmianie ponów `npx robisie doctor`. Rozwiąż też inne błędy doctor: sam licznik 1 nie wystarcza bez końcowego komunikatu sukcesu i exit 0.
+
+Po sukcesie człowiek potwierdza nazwę i cel projektu oraz katalog instalacji, bez klucza i UUID. Przejdź do startu CEO poniżej; to nie jest odbiór karty.
+
+## Start CEO
+
+Człowiek uruchamia CEO w katalogu instalacji.
+
+Po zgodzie człowieka CEO domyślnie wywołuje `spawn_builder` z ID karty potwierdzonej w `ready`.
+
+Przy błędzie `spawn_builder` CEO zgłasza błąd i naprawia przyczynę przed ponowieniem; nie przełącza automatycznie na ręczny start.
+
+Ręczny start to wyłącznie jawny wybór operatora: wtedy CEO podaje polecenie do uruchomienia w nowym terminalu w katalogu instalacji.
+
+W Claude Code CEO uruchamia niezależnego Quality Officera przez `Agent(quality-officer-client)`. Quality Officer sprawdza wynik i zapisuje recenzję oraz dowody; Builder nie recenzuje własnej pracy. CEO weryfikuje potwierdzenie recenzji (verified receipt) i wykonuje świeże odczyty karty przed przejściem do `delivered`; następnie jawny odbiór operatora w panelu pozwala przejść do `done`. Worker nie ustawia `done`. Sam `init`/`doctor` nie daje `done`.
+
+OpenCode: karta pozostaje w `in_review` niezależnie od dostępności narzędzia Agent; brak wspieranego przejścia do `delivered`. Pełny odbiór wymaga opisanej w przewodnikach drogi Claude Code.
+
+Codex: przejście do delivered wymaga niezależnej recenzji oraz zweryfikowanego potwierdzenia (verified receipt). Jeśli w sesji CEO brakuje narzędzia Agent, karta pozostaje w `in_review` i wymaga naprawy integracji przez CEO/CR.
+
+Wszystkie trzy role muszą używać jednego dostawcy; mieszana mapa daje kod 1 doctor. Paczka nie uruchamia usług w tle ani nie zapewnia konta lub dostępu do AI.
+
+Aktualizuj w katalogu instalacji: `npm i robisie@latest` → `npx robisie init` → `npx robisie doctor`. Doctor sprawdza zgodność MAJOR kontraktu serwera; przy niezgodności wybierz zgodne wydanie. Awaryjnie otrzymany plik zainstaluj przez `npm i ./robisie-0.1.0.tgz`; lokalny powrót wymaga poprzedniego zgodnego tgz i kopii konfiguracji. Pełne instrukcje aktualizacji, powrotu i odinstalowania są w przewodnikach.
+
+## Lokalna walidacja rejestru wykonania K7
+
+Zapisz pełną konfigurację K2 i osobny rejestr wykonania w `robisie.config.json`:
+
+```json
+{
+  "project": "uuid-projektu",
+  "tracks": [{"id": "uuid-toru", "name": "Tor główny"}],
+  "stateDir": "./stan",
+  "engine": {
+    "repo": "./repo",
+    "branch": "main",
+    "commands": {
+      "test": ["npm", "test"],
+      "lint": ["npm", "run", "lint"],
+      "build": ["npm", "run", "build:check"]
+    },
+    "requiredChecks": ["test", "lint"],
+    "delivery": "pr"
+  },
+  "roleRegistry": {
+    "worker-client": {"name":"Ola","provider":"codex","model":"gpt-6.1-sol","effort":"high"},
+    "lead-client": {"name":"Leon","provider":"claude","model":"opus","effort":"medium"},
+    "reviewer-client": {"name":"Iga","provider":"opencode","model":"opencode-go/gpt-6-luna","effort":"low"},
+    "tester-client": {"name":"Jan","provider":"grok","model":"grok-cli","effort":"none"}
+  }
+}
+```
+
+Uruchom `npx robisie doctor --engine-config ./robisie.config.json` (także `--engine-config=./robisie.config.json`). Ścieżka pliku jest względem bieżącego katalogu, a `repo` i `stateDir` względem pliku konfiguracji. Role K2 `coordinator/owner/planner/advisor` zachowują domyślne nazwy; opcjonalne pole `roles` służy ich nazwom i odmianie, osobno od `roleRegistry`.
+
+Kod 0 oznacza poprawną konfigurację K2 i dokładnie cztery kompletne przypisania K7; raport pokazuje rolę → imię / dostawcę / model / wysiłek. Kod 1 wskazuje plik, błędne pole (jeśli dotyczy) i następny krok. Ten tryb działa offline, bez klucza, uruchamiania dostawców, wykonywania komend silnika ani zapisu plików. Raport jawnie stwierdza: „sprawdzono konfigurację; nie sprawdzono uruchomienia dostawców”. Zwykły `doctor` zachowuje dotychczasową diagnozę instalacji.
+
+Modele i wysiłki to przykładowe, dosłowne etykiety, bez gwarancji dostępności lub obsługi przez CLI. `grok-cli`/`none` opisują obecny review-job; nie dowodzą sterowania modelem ani wysiłkiem Groka. Imię jest metadanymi rejestru; Execution v1 zachowuje `{contractVersion:1,provider,model,effort}`. Walidacja nie jest odbiorem wykonania karty, dostawców ani całego P-18/K3.

package/dist/active-recovery.d.ts

@@ -0,0 +1,58 @@
+export type CardLike = {
+    detailsReadError?: string | null;
+    id: string;
+    title: string;
+    trackId?: string | null;
+    status?: string | null;
+    assignee?: string | null;
+    details?: Record<string, unknown> | null;
+};
+export declare const ACTIVE_RECOVERY_DETAILS_KEYS: readonly ["maszynista", "review", "reksio_withheld"];
+export type Active = {
+    taskId: string;
+    title: string;
+    trackId: string | null;
+    jobId: string;
+    worktree: string;
+    branch: string;
+    startedAt: string;
+    attempts: number;
+    backend?: "claude" | "codex" | "grok-cli" | "opencode";
+    model?: string;
+    opencode?: Readonly<{
+        pid: number;
+        pidPath: string;
+        promptPath: string;
+        stdoutPath: string;
+        stderrPath: string;
+        exitPath: string;
+        startedAt: string;
+        jobId: string;
+        model: string;
+        provider: "opencode-go";
+        sessionId: string | null;
+        messageId: string | null;
+    }>;
+};
+export declare function reconcileActive(input: {
+    stateActives: Active[];
+    boardCards: CardLike[];
+    assignee: string;
+    nowIso: string;
+}): {
+    actives: Active[];
+    releases: Array<{
+        taskId: string;
+        status: "ready";
+        assignee: null;
+    }>;
+    adopted: Array<{
+        active: Active;
+        stamp: Record<string, unknown>;
+        orphan?: CardLike;
+    }>;
+    skipped?: Array<{
+        card: CardLike;
+        reason: string;
+    }>;
+};

package/dist/active-recovery.js

@@ -0,0 +1,143 @@
+export const ACTIVE_RECOVERY_DETAILS_KEYS = ["maszynista", "review", "reksio_withheld"];
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+    return record(value) ? value : {};
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function nonempty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function timestamp(value) {
+    return nonempty(value) && Number.isFinite(Date.parse(value));
+}
+export function reconcileActive(input) {
+    const previous = new Map(input.stateActives.map((active) => [active.taskId, active]));
+    const actives = [];
+    const releases = [];
+    const adopted = [];
+    const skipped = [];
+    const takeState = (card, fromState, worker) => {
+        const active = {
+            ...fromState,
+            title: card.title,
+            trackId: nonempty(card.trackId) ? card.trackId : null,
+        };
+        const meta = record(worker) ? worker : {};
+        const stamp = {
+            branchLease: meta.branchLease ?? null,
+            at: fromState.startedAt,
+            jobId: fromState.jobId,
+            worktree: fromState.worktree,
+            branch: fromState.branch,
+            attempts: fromState.attempts,
+            outcome: "dispatched",
+        };
+        if ("engine" in meta)
+            stamp.engine = meta.engine;
+        if (fromState.backend)
+            stamp.backend = fromState.backend;
+        if (fromState.model)
+            stamp.model = fromState.model;
+        if (fromState.opencode)
+            stamp.opencode = fromState.opencode;
+        actives.push(active);
+        adopted.push({ active, stamp });
+    };
+    for (const card of input.boardCards) {
+        const orphan = card.status === "in_review" && card.assignee == null && !previous.has(card.id);
+        if (card.assignee !== input.assignee && !orphan)
+            continue;
+        if (orphan) {
+            const worker = asRecord(card.details?.maszynista);
+            if (card.detailsReadError || card.details?.reksio_withheld === true
+                || worker.processStart != null)
+                continue;
+            if (worker.outcome === "ACTIONABLE_BLOCKER") {
+                skipped.push({ card, reason: "outcome=ACTIONABLE_BLOCKER — powrót przez blocked/ready" });
+                continue;
+            }
+            if (!["review", "landing"].includes(String(worker.phase))
+                || (worker.outcome !== "WORKER_FINISHED" && asRecord(card.details?.review).verdict !== "PASS"))
+                continue;
+            if (![worker.jobId, worker.worktree, worker.branch].every(nonempty) || !positiveInteger(worker.attempts)) {
+                skipped.push({ card, reason: "niepełne dane Workera (jobId, worktree, branch, attempts)" });
+                continue;
+            }
+        }
+        if (card.detailsReadError) {
+            const known = previous.get(card.id);
+            if (known)
+                actives.push(known);
+            continue; // No release/restamp can be justified without readable process identity.
+        }
+        const details = card.details ?? {};
+        const worker = details.maszynista;
+        const activeStatus = card.status === "in_progress"
+            || (card.status === "in_review" && record(worker) && ["review", "landing"].includes(String(worker.phase)));
+        if (!activeStatus)
+            continue;
+        const fromState = previous.get(card.id);
+        const cardJobId = record(worker) && nonempty(worker.jobId) ? worker.jobId : null;
+        // State wins: no jobId; different jobId without valid `at`; different jobId with older/equal `at`.
+        // Same jobId → card wins. Different jobId with strictly newer valid `at` → card wins. Attempts unused.
+        if (fromState && !cardJobId) {
+            takeState(card, fromState, worker);
+            continue;
+        }
+        if (fromState && cardJobId && cardJobId !== fromState.jobId) {
+            const cardAt = record(worker) ? worker.at : undefined;
+            const cardNewer = timestamp(cardAt) && Date.parse(cardAt) > Date.parse(fromState.startedAt);
+            if (!cardNewer) {
+                takeState(card, fromState, worker);
+                continue;
+            }
+        }
+        if (!record(worker) || !cardJobId) {
+            releases.push({ taskId: card.id, status: "ready", assignee: null });
+            continue;
+        }
+        const attempts = worker.attempts ?? worker.attempt;
+        // A known job must not be released and dispatched twice just because metadata is incomplete.
+        if (!nonempty(worker.worktree) || !nonempty(worker.branch) || !positiveInteger(attempts)) {
+            throw new Error(`Niepełne dane workera na karcie ${card.id}`);
+        }
+        if (worker.backend !== undefined && worker.backend !== "codex" && worker.backend !== "opencode") {
+            if (orphan) {
+                skipped.push({ card, reason: "nieobsługiwany backend Workera" });
+                continue;
+            }
+            throw new Error(`Nieobsługiwany backend workera na karcie ${card.id}`);
+        }
+        if ((worker.opencode !== undefined && worker.backend !== "opencode")
+            || (worker.backend === "opencode" && (!record(worker.opencode)
+                || !positiveInteger(worker.opencode.pid) || !nonempty(worker.model)
+                || ![worker.opencode.pidPath, worker.opencode.promptPath, worker.opencode.stdoutPath,
+                    worker.opencode.stderrPath, worker.opencode.exitPath,
+                    worker.opencode.jobId, worker.opencode.model].every(nonempty)
+                || worker.opencode.jobId !== cardJobId || worker.opencode.model !== worker.model
+                || worker.opencode.provider !== "opencode-go"))) {
+            if (orphan) {
+                skipped.push({ card, reason: "niepełna tożsamość OpenCode" });
+                continue;
+            }
+            throw new Error(`Niepełna tożsamość OpenCode na karcie ${card.id}`);
+        }
+        const old = previous.get(card.id);
+        const active = {
+            taskId: card.id, title: card.title, trackId: nonempty(card.trackId) ? card.trackId : null,
+            jobId: cardJobId, worktree: worker.worktree, branch: worker.branch, attempts,
+            startedAt: timestamp(worker.at) ? worker.at : old?.startedAt ?? input.nowIso,
+            ...(worker.backend === "opencode" || worker.backend === "codex" ? { backend: worker.backend } : {}),
+            ...(nonempty(worker.model) ? { model: worker.model } : {}),
+            ...(record(worker.opencode) ? { opencode: worker.opencode } : {}),
+        };
+        actives.push(active);
+        if (orphan)
+            adopted.push({ active, stamp: worker, orphan: card });
+    }
+    return { actives, releases, adopted, ...(skipped.length ? { skipped } : {}) };
+}

package/dist/agents.d.ts

@@ -0,0 +1,34 @@
+import { type Ctx } from "./context.js";
+import { type Op } from "./fsops.js";
+import { type Role } from "./roles.js";
+export declare const AGENT_IDS: readonly ["claude", "codex", "opencode"];
+export type AgentId = (typeof AGENT_IDS)[number];
+export declare const AGENT_LABELS: Record<AgentId, string>;
+export declare function isAgentId(value: string): value is AgentId;
+/** Where each agent keeps its user-level configuration (the same places the agents themselves read). */
+export declare function agentPaths(ctx: Ctx): {
+    clientDir: string;
+    claudeDir: string;
+    claudeJson: string;
+    codexHome: string;
+    codexConfig: string;
+    codexAgentsMd: string;
+    opencodeDir: string;
+    opencodeJson: string;
+    opencodeJsonc: string;
+};
+export declare function agentOnPath(ctx: Ctx, id: AgentId): boolean;
+/** Detection reads only the filesystem (config dir present, or binary on PATH) — nothing is executed. */
+export declare function detectAgents(ctx: Ctx): AgentId[];
+/** Keep a multiline string or array in its assignment, so its contents cannot look like server headers. */
+export declare function tomlStatements(text: string): string[];
+/**
+ * Take over an `[mcp_servers.robisie]` table written earlier by hand or by `codex mcp add` (otherwise
+ * Codex would see the table twice and refuse the whole config). Backups retain the old configuration.
+ */
+export declare function removeCodexTables(text: string, removeInline?: boolean, codexHome?: string): string;
+/** Every file change `init` makes for one agent. */
+export declare function planAgent(ctx: Ctx, id: AgentId, roles: readonly Role[], key: string): Op[];
+/** Shell profile line that exports ROBISIE_KEY from the package's key file (roles and Codex/OpenCode read it). */
+export declare function shellProfile(ctx: Ctx): string | null;
+export declare const SHELL_EXPORT = "[ -r \"${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key\" ] && export ROBISIE_KEY=\"$(cat \"${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key\")\"";