@wjarka/cezarion 0.14.8 → 0.14.9-dev.1009

package/README.md

@@ -38,6 +38,19 @@ That's the whole setup. If your `claude` CLI is logged in (Pro/Max) and `gh` is
 authenticated, there is nothing else to configure. State lives in `.ai/cezar/`
 inside your repo — plain JSON, NDJSON and Markdown you can `cat` and fix by hand.
 
+Local npm installations have a workspace update API. `POST
+/api/v1/workspace/application-update/apply` with `{}` prepares the release
+advertised by health while the current server keeps running; `POST
+/api/v1/workspace/application-update/restart` with `{}` then restarts it. A
+successful restart updates the original global installation or ordinary npx
+cache entry, so the same command uses the new version on its next launch.
+Update preparation and recovery state is generated under
+`~/.cezar/application-updates/` (or `CEZ_HOME`).
+Pinned npx invocations, source checkouts, npm links, and hosted deployments use
+their existing manual update paths. Cezar holds its own installation lock and
+npm's npx lock during promotion; a separate manual `npm install` does not honor
+those locks, so avoid one while an update is preparing or restarting.
+
 ## A look inside
 
 Click any thumbnail for the full-size screenshot.
@@ -202,7 +215,7 @@ Every green CI run also publishes an installable npm snapshot
 merged yet:
 
 ```bash
-npx cezarion@develop       # current develop head
+npx cezarion@dev           # current main head
 ```
 
 Every pull request gets its own preview too — the CI bot posts a sticky comment
@@ -495,6 +508,21 @@ not settings to create or share. If the tool is unavailable or denied, its error
 is surfaced while ordinary tasks continue. See [the CI-wait protocol](AGENT_PROTOCOL.md#ci-wait-tool-contract-474)
 for limits and the executable harness verification required before release.
 
+## Discover runners and models
+
+Inspect the same host catalog the cockpit uses before selecting a runner or model:
+
+```sh
+cez discover runners
+cez discover models --runner=codex
+```
+
+Both commands return JSON. `runners` lists connection status (`connected`, `disconnected`, `not-installed`, or `unknown`) and enablement, with `scope: "host-default-account"`. Model rows include `effortLevels` when the runner advertises them: an absent field means unknown; an empty array means no advertised levels. Omit `--effort` when spawning to keep the existing default. Model responses retain `source`, `stale`, and any unavailable `reason`; discovery never invents model IDs or effort support.
+
+For operators, the command finds the running cockpit for the current checkout; `--repo`, `--url`, and `CEZ_URL` work as they do for `cez task`. A missing cockpit returns an error and never starts a server. Inside a parent delegation session, the same command uses that session's authenticated controller, including headless runs. It rejects `--url` and `--repo` in that context and never falls back to a public cockpit after an authentication failure. Owned workers cannot use the private discovery route.
+
+The catalog describes host default accounts, not every named account or the selections permitted by a task's model locks and workflow pins. Existing `cez task start` and `cez worker spawn` still call their runner flag `--backend`; discovery uses `--runner`.
+
 ## Owned workers (opt-in)
 
 Start the cockpit or a headless task with `CEZ_DELEGATION=1`. Each eligible parent session receives the absolute bundled Node/CLI invocation and its own environment credentials; no `cez` installation on the agent's PATH, config file, separate daemon, or remembered port is needed. If the private listener cannot start, ordinary tasks keep working without delegation tools. `.env` is never loaded automatically.
@@ -528,8 +556,12 @@ cez worker destroy <worker-id>
 
 Use `cez worker --help` to list operations and flags, or `cez worker <operation> --help` for one operation. Explicit help prints human-readable text and exits successfully without an active delegation session. Commands otherwise return bounded JSON and a nonzero exit on failure or incomplete cleanup. Spawn requires a committed baseline (`parent-head` or an explicit ref) and pins its SHA at acceptance; dirty parent edits are excluded. Optional `--context '<text>'` or `--context-file <UTF-8-file>` supplies selected context, not the parent's conversation. The two flags are mutually exclusive, and combined task/context text is limited to 100,000 characters. The API also accepts up to 32 pinned-baseline file or parent-attachment references, with at most 8 MiB of copied attachments. Inspect reports worker-local input locations. Reuse a request ID only with the same task, baseline, context, backend, model, effort and workflow when retrying a lost response. There are at most 32 accepted creations per parent, counting destroyed workers, and 32 undelivered steering messages per worker.
 
+An incomplete destroy reports the remaining resources and a reason. Cezar retries that recorded request after a delay, including after the project's context recovers on server restart. It removes the owned checkout only after process termination and ownership are verified. If the reason persists, inspect the worker process, Git worktree lock and ownership receipt; correct the blocker and use `cez worker destroy <worker-id>` or the cockpit Destroy action to retry immediately. Cezar leaves ambiguous or replaced resources in place for operator review.
+
 `--workflow <name>` runs a catalog workflow inside the worker: the built-in `quick-task` or any `.ai/cezar/workflows/*.yaml` by name, with its agent and check steps, `skill:` bodies and `onFail` loops, so a repo's `review.yaml` becomes a dedicated reviewer. Omitted `--workflow` runs `quick-task` exactly as before. `--backend`, `--model` and `--effort` fill only the steps that leave those fields unset; a step's own `allowedTools`/`bashAllowlist` narrow the parent's grants and never widen them. An unknown name is refused. Agent steps may mix runners: at spawn every agent step is resolved and pinned separately, so an implement-with-codex, review-with-claude chain runs each step under its own runner, account, model, effort and grants. A step's optional `agentProfile` names the account it runs under (an id the registry does not know is refused); same-backend steps otherwise inherit the parent's account and other runners resolve their project/default one. Run-level columns show the first agent step.
 
+Explicit default-account model pins are checked against a fresh, nonempty host catalog after account/model resolution and before a worker is created. Named accounts retain existing validation because a default-account catalog cannot disprove their model access. A miss returns `invalid_input`, available models with advertised efforts, and other runners listing the requested ID in `modelChoices`. Empty, stale, or unavailable discovery leaves existing selection validation in place. Accepted retries and omitted model defaults are unchanged.
+
 Omitted `--backend` inherits the parent's active backend. Same-backend workers inherit omitted model/account/effort; `--backend <claude|codex|opencode|pi|cursor>` selecting another backend resolves that backend's project/default account and model without forwarding another provider's settings. `--model <model>` selects a supported model, subject to existing locks. `--effort <low|medium|high|xhigh|max>` pins reasoning effort on same-backend and mixed-backend spawn; omitted `--effort` still inherits the parent pin on same-backend spawn and drops it on mixed-backend spawn. Accepted identity and grants remain fixed across queuing, restart and Continue, including explicit empty grants. Changing or deleting an account registry entry does not rebind a worker. Missing accepted identity evidence or account homes, incompatible Claude state-file layouts, and conflicting later model locks refuse execution explicitly. Credentials and vendor configuration are never copied; each worker receives its own delegation credential, and unspecified native models stay unspecified.
 
 Wait registers immediately. End the parent turn to release scheduler capacity; Cezar resumes it on a selected settled outcome or the finite deadline. `any` is the default, `one` requires exactly one worker, and `all` waits for every selected worker. Review, completion, failure, cancellation with proven termination, and destruction are outcomes. Timeout defaults to 600 seconds (1–1800 accepted). `cancel-wait` is idempotent for the retained wait ID and cannot cancel a newer wait. Timeout and wait cancellation report partial outcomes and unresolved workers, never cancel workers, and never automatically re-wait. Steering is attributed agent input and cannot answer a pending human question.
@@ -538,7 +570,7 @@ Parents and owned workers can converse in both directions; a worker may address
 
 Messages allow 100,000 characters each, with at most 32 undelivered inputs per recipient, 1,024 messages per family, and 32 pending requests. Request deadlines default to 600 seconds, configurable per message with `--timeout-seconds 1–1800`. Request waits use the same limits and `one`/`any`/`all` modes as worker waits, and each run has one active wait. Incoming conversation can interrupt a parked wait without settling its requests. `cancel-request` cancels an obligation; `cancel-wait` only stops waiting. Completion without a reply, failure, cancellation, destruction, timeout, or sender closure settle obligations distinctly. Late replies remain visible without reopening them.
 
-Pending conversations are delivered together at the next safe turn boundary, in order, up to 32 messages and 100,000 formatted characters per batch. A single valid message is never split. Messages arriving during that turn wait for the next boundary. Every message retains its ID, sender, delivery receipt and request outcome. Human questions, active turns and scheduler capacity can delay delivery. The thread's Details distinguish creation, delivery confirmation and event-recording times.
+Messages reach a live recipient as soon as they are accepted, including mid-turn: Claude, Codex, Pi and OpenCode steer them into the running turn, and the model reads them at its next step. Cursor delivers at the turn boundary, because a second prompt would cancel its running turn. Pending conversations go together, in order, up to 32 messages and 100,000 formatted characters per batch; a single valid message is never split. Every message keeps its ID, sender, delivery receipt and request outcome; receipts show queued, delivered and read (when the agent's harness can tell) separately. A pending human question holds messages until it is answered, then they follow right behind the answer. The thread's Details distinguish creation, delivery confirmation and event-recording times.
 
 Sending to a review or terminal participant without `--resume` reports `not-delivered` and `continuation-required`, with the reason and next command; the CLI exits 1. An active parent can use `worker send --resume` (request or progress) to continue its settled done/review/failed worker with that message as the new instruction. No human Continue is needed for this parent-controlled action. A retry with the same payload and ID never creates another continuation; changing a rejected send to use `--resume` requires a new ID. Stopped or destroyed workers need a new worker. Workers cannot resume parents, and conversation never answers a pending human question. Durable IDs deduplicate accepted queue entries and event replay, but a crash between provider acceptance and its durable delivery checkpoint can leave transport delivery ambiguous; this is not an exactly-once execution guarantee.
 
@@ -552,6 +584,67 @@ Stop requests cancellation; `stopping` does not prove termination. Destroy check
 Provisioned sessions prefer cezar workers and suppress verified native delegation entry points through per-run adapter controls: Claude `Agent`/legacy `Task` denies, Codex multi-agent feature overrides, OpenCode session `task` denies, and pi's known `subagent` extension exclusion. See [the backend capability table](AGENT_PROTOCOL.md#governed-delegation-controls-d1) for tested versions and exemptions. Native workers are not tracked by cezar. Pi has no native delegation primitive or universal identifier for arbitrary custom delegation extensions; guidance does not enforce those cases. With delegation disabled or unavailable, ordinary tools/settings stay unchanged. The listener binds to `127.0.0.1`, including hosted cockpit mode. Its credentials authorize only the parent's own workers through that listener. This is cooperative local-agent supervision; same-user unrestricted shell and custom tools are not hard isolation. Workers cannot delegate or message peers through cezar. Review remains a human gate with no automatic acceptance. Never read, echo, forward, or persist the generated token.
 
 
+## From the terminal: `cez task`
+
+`cez task` starts, watches and steers tasks **in the running cockpit** from a shell — for you, or
+for a bot driving one. Every command prints one JSON object and exits with a code the caller can
+branch on, so nothing has to parse prose. It never starts a server: it finds the cockpit whose
+project registry holds this checkout (ports 4321–4370; a task worktree resolves to its parent
+project), or you point it at one with `--url` / `CEZ_URL`.
+
+```bash
+id=$(cez task start --task-file - <<'EOF' | jq -r .id
+Fix the `cez task` docs. Keep $(example) and "quotes" literal.
+EOF
+)
+cez task wait "$id" --until attention --timeout-seconds 900   # 0 done/review · 1 failed · 3 timeout
+cez task status "$id"                                         # slim JSON: status, question, branch, diffStat…
+cez task send "$id" 'Use the retry helper instead'            # queued, delivered, or --resume to reopen
+cez task log "$id" --follow --timeout-seconds 300             # JSON lines until it ends
+```
+
+Use `--task-file PATH` to read a saved task (for example, `cez task start --task-file task.md`),
+or `--task-file -` to read stdin as above. The quoted heredoc delimiter (`<<'EOF'`) keeps
+backticks and `$()` literal in the task text.
+
+POSIX shells, including Bash, expand backticks and `$()` in double-quoted arguments before
+cez receives the text. **Do not put raw backticks in double-quoted task arguments.** This can
+execute parts of your prompt as shell commands and leave holes in the stored task, including
+when starting tasks through SSH and `bash -lc`. Prefer a task file or stdin with a quoted
+heredoc delimiter. A single-quoted positional argument still works for short tasks:
+`cez task start 'Fix the typo'`.
+
+`cez task start --task-file task.md --skill <name>` names one skill as the task's agent step;
+`--skill` and `--workflow` are mutually exclusive. The CLI checks `GET /skills` first and
+includes a `warning` in its JSON result if the skill is missing or the catalog cannot be
+checked; it still starts the run. Like a cockpit skill start, if the skill is missing at
+execution, the agent uses the plain prompt and the run logs a note. CLI starts do not change
+the cockpit composer's recent picks or skill-usage ranking.
+Without either flag, `start` still runs `quick-task`.
+
+`start` is retry-safe: it sends a request id (`--request-id <UUID>` to pick your own), and a
+retry with the same id and task answers with the run the first one created (`created: false`)
+instead of starting a second. Also: `list`, `stop`, `finish`, `diff [--stat]`, `open`.
+Use `archive <id>` to hide a task from `list`, `unarchive <id>` to restore it, and
+`list --all` to include archived tasks. `archive-finished` sweeps finished tasks and prints
+`{"archived": count}`. The single-task commands print `{"id": "…", "archived": true|false}`.
+Exit codes:
+`0` ok, `1` task failed/cancelled or a message was not delivered, `2` no cockpit or the cockpit
+refused (its `error` is passed through), `3` timed out, `64` usage error. `cez task --help` lists
+every flag.
+
+**A bot that lives behind an HTTP endpoint** does not have to poll. Set a **Task webhook** (URL
+and an optional Bearer token) in the project's **Settings → General**, and every task that opts
+in POSTs `task.status` on each status change, `task.question` when it asks something,
+`task.activity` when monitoring starts or ends, and `task.subscribed` when it opts in (at start, or when it is handed off). Each
+body carries the same slim projection `cez task status` prints, under `task`. `cez task start`
+opts in whenever the project has a webhook (`--no-notify` to skip it); the cockpit's New task form
+has a **Notify webhook** toggle; and a running task's **Hand off** button (or
+`cez task notify <id> --message '…'`) turns it on later with a note for the bot. The note goes to
+the webhook only, never to the agent. Delivery is best-effort: 10 s timeout, 3 attempts, and a
+failure shows in the thread without touching the task. The token is stored in `~/.cezar` and never
+sent back to a browser. Under `CEZ_DRY_RUN=1` nothing is sent; the payload is logged in the thread.
+
 ## Workflow format
 
 A workflow is a small YAML file in `.ai/cezar/workflows/`:
@@ -611,6 +704,7 @@ Useful environment variables:
 |---|---|
 | `CEZ_DELEGATION=1` | Enable owned workers and the private loopback listener for this controller. Off by default; works with the cockpit and headless `cez run`. Session instructions and credentials are automatic. |
 | `CEZ_DELEGATION_URL`, `CEZ_DELEGATION_TOKEN` | Internal generated session values; do not configure or copy them. Tokens rotate on Continue/restart and are revoked when the session/controller closes. |
+| `CEZ_URL` | Cockpit origin for `cez task` and operator `cez discover` (e.g. a hosted `CEZ_REMOTE` cockpit). Unset, they find the local cockpit serving this checkout on ports 4321–4370. Parent discovery uses its delegation controller instead. |
 | `CEZ_DRY_RUN=1` | Use bundled mocks for all five agent backends — the cockpit works offline for demos and development. Explicit backend binary overrides still win. |
 | `CEZ_AGENT_MODELS_LOCKED=1` | Globally lock each runner to the model configured in its native Claude/Codex/OpenCode settings while keeping runner selection available. Exact `1` also delegates authentication and provider enablement to those native agents, so Cezar skips its credential probes and provider-disable preferences. Existing Cezar presets are preserved but ignored, and an environment change requires a restart. The config-file equivalent is `"modelsLocked": true` in global `~/.cezar/config.json` or one repository's `.ai/cezar/config.json`; config-file locks do not disable provider checks. |
 | `CEZ_APPROVAL_GATE=1` | Opt into Claude's interactive approval UI; by default, unapproved tools are denied without interrupting the run. Ignored when `CEZ_CLAUDE_PERMISSION_MODE` is a recognized value (`dontAsk`, `acceptEdits`, or `bypass`). |
@@ -645,6 +739,7 @@ Useful environment variables:
 | `CEZ_REVIEW_GATE=1` | Turn ON the optional diff-first review gate (#489): a successful, non-autonomous run with changes parks at `review` (Accept / Send back / Draft PR) instead of finishing. Off by default — changed runs settle to `done` with the diff left in the worktree. Only `1` enables. The Settings → Agents toggle overrides this; autonomous runs always skip it. |
 | `CEZ_NO_BANNER=1` | Skip the `open-mercato/skills` banner on `cez serve` startup. (The cockpit no longer shows a banner — its skills now live on the Skills page's Manage panel — so this env var is the terminal banner's only switch.) |
 | `VITE_CEZ_API_BASE=http://localhost:4321` | **Build time only**, and only when the cockpit bundle is deployed apart from the service it talks to. Empty (the default) means "the origin that served this page", which is right for both normal cases: the CLI serves the bundle itself, and `npm run dev` proxies `/api` to the local service. A deployment that must be configured without a rebuild can put `<meta name="cez-api-base" content="…">` in the served HTML instead, which wins over this. |
+| `VITE_CEZ_E2E=1` | **Build time only.** The cockpit e2e suite sets this when it builds the bundle it drives. It pins `useNow` and every `refetchInterval` so a wait cannot span a 30s tick or a 4s poll. Leave unset for production. |
 
 ### Troubleshooting: the agent's shell returns nothing
 
@@ -834,6 +929,32 @@ works and how to redeploy new versions.
 
 ---
 
+## Reviewing task files
+
+File links in task messages open the Files tab at the selected file, rather than
+navigating to a host path under the cockpit URL. The selection stays in the URL,
+so bookmarks and browser Back work. This works with local and remote cockpits.
+
+For a deliverable outside the project, an agent must explicitly publish a snapshot:
+
+```sh
+cez artifact publish /tmp/decision.md
+```
+
+Cezar supplies the bundled command and task context to agent sessions automatically
+(`CEZ_TASK_ID` and `CEZ_ARTIFACTS_DIR`; do not configure these yourself). The command
+returns JSON with a Markdown link for the agent to share. The Files tab also lists
+published artifacts. It previews text, Markdown and raster images; other formats
+can be downloaded. HTML/scripts never execute inside the cockpit, and embedded
+images in Markdown documents do not load automatically.
+
+Snapshots do not change when the original file changes. They survive worktree
+removal and are removed with task history, including normal history retention.
+Publication is limited to 10 MiB per file, 64 snapshots and 64 MiB per task; reaching
+a limit refuses the new publication without evicting earlier files. There is no
+arbitrary host-file reader or automatic collection of mentioned paths. Publish
+only intended review material, never credentials or unrelated private files.
+
 ## Configuration (optional)
 
 Zero config is the default — everything below is opt-in via
@@ -965,11 +1086,19 @@ npm run build        # tsc → packages/cezar/dist/, vite build → packages/cez
 npm run typecheck    # refresh server declarations, then check all four workspaces
 npm run typecheck:web # refresh server declarations, then check web sources
 npm test             # vitest — server + cockpit unit suites
+npm run test:changed # iteration only: tests related to branch + working-tree changes
 npm run test:unit    # node:test — fast core-module tests
 npm run test:package # pack/install and exercise the built CLI
 npm run test:e2e     # real-browser cockpit suite (agent-browser)
 ```
 
+For iteration, run affected test files or `npm run test:changed` (inspect with
+`-- --plan`; override the local main comparison with `-- --base=<ref>`).
+The changed-test command includes staged, unstaged and untracked changes and
+falls back to full Vitest on shared/configuration/unknown input or missing Git
+history. It is not a substitute for final verification. See `AGENTS.md` § Validation
+for targeted browser commands and the final-gate/evidence-reuse policy.
+
 Both `npm run typecheck:web` and
 `npm run typecheck -w @open-mercato/cezar-web` rebuild server declarations from
 the current checkout before checking web sources. Run `npm ci` in each new

package/dist/application-update/bin-recovery.d.ts

@@ -0,0 +1,5 @@
+/** Discovery already proved one of these two canonical global layouts. */
+export declare function windowsGlobalLayout(prefix: string, outerRoot: string, outerPackage: string): boolean;
+export declare function snapshotGlobalBins(directory: string, names: string[], windows: boolean, destination: string, assertOwned: () => Promise<void>): Promise<void>;
+/** Validate the entire private snapshot before touching any command path. */
+export declare function restoreGlobalBins(prefix: string, names: string[], windows: boolean, source: string, assertOwned: () => Promise<void>): Promise<void>;

package/dist/application-update/bin-recovery.js

@@ -0,0 +1,96 @@
+import { chmod, lstat, readFile, readlink, rm, symlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const validName = (name) => typeof name === 'string' && /^[a-zA-Z0-9-]+$/.test(name);
+const fail = () => { throw new Error('invalid recovery command snapshot'); };
+/** Discovery already proved one of these two canonical global layouts. */
+export function windowsGlobalLayout(prefix, outerRoot, outerPackage) {
+    return outerRoot === join(prefix, 'node_modules', outerPackage);
+}
+function filenames(names, windows) {
+    if (!names.every(validName))
+        fail();
+    return names.flatMap(name => windows ? [name, `${name}.cmd`, `${name}.ps1`] : [name]);
+}
+export async function snapshotGlobalBins(directory, names, windows, destination, assertOwned) {
+    const entries = [];
+    for (const name of filenames(names, windows)) {
+        await assertOwned();
+        const path = join(directory, name);
+        const info = await lstat(path).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error; // Permission and I/O failures must not become "absent".
+        });
+        if (!info)
+            entries.push({ name, kind: 'absent' });
+        else if (info.isSymbolicLink())
+            entries.push({ name, kind: 'link', target: await readlink(path) });
+        else if (info.isFile())
+            entries.push({ name, kind: 'file', bytes: (await readFile(path)).toString('base64'), mode: info.mode & 0o777 });
+        else
+            throw new Error('unsupported npm command file');
+    }
+    await assertOwned();
+    await writeFile(destination, JSON.stringify({ version: 1, windows, entries }), { mode: 0o600 });
+}
+/** Validate the entire private snapshot before touching any command path. */
+export async function restoreGlobalBins(prefix, names, windows, source, assertOwned) {
+    const raw = JSON.parse(await readFile(source, 'utf8'));
+    const allowed = new Set(filenames(names, windows));
+    let entries;
+    // Keep already-prepared POSIX updates resumable across this change.
+    if (Array.isArray(raw)) {
+        if (windows)
+            fail();
+        entries = raw.map((link) => {
+            if (!link || typeof link !== 'object')
+                return fail();
+            const item = link;
+            if (!allowed.has(item.name) || typeof item.target !== 'string')
+                return fail();
+            return { name: item.name, kind: 'link', target: item.target };
+        });
+    }
+    else {
+        if (!raw || typeof raw !== 'object')
+            fail();
+        const snapshot = raw;
+        if (snapshot.version !== 1 || snapshot.windows !== windows || !Array.isArray(snapshot.entries))
+            fail();
+        const seen = new Set();
+        entries = snapshot.entries.map((value) => {
+            if (!value || typeof value !== 'object')
+                return fail();
+            const entry = value;
+            if (typeof entry.name !== 'string' || !allowed.has(entry.name) || seen.has(entry.name))
+                return fail();
+            seen.add(entry.name);
+            if (entry.kind === 'absent')
+                return { name: entry.name, kind: 'absent' };
+            if (entry.kind === 'link' && typeof entry.target === 'string' && !entry.target.includes('\0')) {
+                return { name: entry.name, kind: 'link', target: entry.target };
+            }
+            if (entry.kind === 'file' && typeof entry.bytes === 'string' && Buffer.from(entry.bytes, 'base64').toString('base64') === entry.bytes
+                && typeof entry.mode === 'number' && Number.isInteger(entry.mode) && entry.mode >= 0 && entry.mode <= 0o777) {
+                return { name: entry.name, kind: 'file', bytes: entry.bytes, mode: entry.mode };
+            }
+            return fail();
+        });
+        if (seen.size !== allowed.size)
+            fail();
+    }
+    const directory = windows ? prefix : join(prefix, 'bin');
+    for (const entry of entries) {
+        await assertOwned();
+        const path = join(directory, entry.name);
+        await rm(path, { force: true }); // Do not follow replaced symlinks or remove directories.
+        await assertOwned();
+        if (entry.kind === 'link')
+            await symlink(entry.target, path);
+        if (entry.kind === 'file') {
+            await writeFile(path, Buffer.from(entry.bytes, 'base64'), { mode: entry.mode, flag: 'wx' });
+            await chmod(path, entry.mode);
+        }
+    }
+}
+//# sourceMappingURL=bin-recovery.js.map

package/dist/application-update/bin-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-recovery.js","sourceRoot":"","sources":["../../src/application-update/bin-recovery.ts"],"names":[],"mappings":"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"}

package/dist/application-update/discovery.d.ts

@@ -0,0 +1,22 @@
+export type Installation = {
+    kind: 'unsupported';
+    reason: string;
+} | {
+    kind: 'global' | 'npx';
+    prefix: string;
+    cache: string;
+    installRoot: string;
+    packageRoot: string;
+    outerRoot: string;
+    launchEntry: string;
+    outerPackage: '@wjarka/cezarion' | 'cezarion';
+    request: string;
+};
+export interface DiscoveryInput {
+    prefix: string;
+    cache: string;
+    packageRoot: string;
+    launchEntry: string;
+}
+/** Match only npm-owned, canonical layouts. A matched but unsafe layout is explicit. */
+export declare function discoverInstallation(input: DiscoveryInput): Installation;

package/dist/application-update/discovery.js

@@ -0,0 +1,91 @@
+import { realpathSync, readFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+function inside(path, root) {
+    const rel = relative(root, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+function json(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** Match only npm-owned, canonical layouts. A matched but unsafe layout is explicit. */
+export function discoverInstallation(input) {
+    const unsupported = (reason) => ({ kind: 'unsupported', reason });
+    try {
+        let prefix;
+        try {
+            prefix = realpathSync(input.prefix);
+        }
+        catch {
+            prefix = resolve(input.prefix);
+        }
+        // A fresh global npm install need not have created its cache yet.
+        let cache;
+        try {
+            cache = realpathSync(input.cache);
+        }
+        catch {
+            cache = resolve(input.cache);
+        }
+        const packageRoot = realpathSync(input.packageRoot);
+        const launchEntry = realpathSync(input.launchEntry);
+        const manifest = json(join(packageRoot, 'package.json'));
+        if (manifest.name !== '@wjarka/cezarion' || typeof manifest.version !== 'string') {
+            return unsupported('running package is not @wjarka/cezarion');
+        }
+        let kind;
+        let installRoot;
+        let modules;
+        if (inside(packageRoot, join(prefix, 'lib/node_modules')) || inside(packageRoot, join(prefix, 'node_modules'))) {
+            kind = 'global';
+            installRoot = prefix;
+            modules = inside(packageRoot, join(prefix, 'lib/node_modules')) ? join(prefix, 'lib/node_modules') : join(prefix, 'node_modules');
+        }
+        else {
+            const parts = relative(cache, packageRoot).split(sep);
+            if (parts[0] !== '_npx' || !/^[a-z0-9]+$/i.test(parts[1] ?? '') || parts[2] !== 'node_modules') {
+                return unsupported('not an npm global or npx cache installation');
+            }
+            kind = 'npx';
+            installRoot = join(cache, '_npx', parts[1]);
+            modules = join(installRoot, 'node_modules');
+        }
+        const direct = join(modules, '@wjarka/cezarion');
+        const alias = join(modules, 'cezarion');
+        let outerPackage;
+        if (packageRoot !== direct && packageRoot !== join(alias, 'node_modules/@wjarka/cezarion')) {
+            return unsupported('linked or mixed package layout');
+        }
+        outerPackage = inside(launchEntry, alias) ? 'cezarion' : '@wjarka/cezarion';
+        let request = outerPackage;
+        if (kind === 'npx') {
+            const root = json(join(installRoot, 'package.json'));
+            const requests = root._npx?.packages;
+            if (!Array.isArray(requests) || requests.length !== 1 ||
+                !['cezarion', '@wjarka/cezarion'].includes(requests[0])) {
+                return unsupported('pinned or mixed npx request');
+            }
+            request = requests[0];
+            // npm may link .bin/cezarion to the scoped dependency even when the _npx
+            // request and root dependency are the alias. Metadata owns this choice.
+            outerPackage = request;
+        }
+        if (outerPackage === '@wjarka/cezarion' && packageRoot !== direct)
+            return unsupported('mixed launch layout');
+        const outerPath = outerPackage === 'cezarion' ? alias : direct;
+        if (!inside(launchEntry, outerPath) && !(kind === 'npx' && inside(launchEntry, packageRoot))) {
+            return unsupported('launch entry does not belong to installation');
+        }
+        if (outerPackage === 'cezarion') {
+            const outer = json(join(alias, 'package.json'));
+            const deps = outer.dependencies;
+            if (outer.name !== 'cezarion' || typeof deps?.['@wjarka/cezarion'] !== 'string')
+                return unsupported('alias is not linked to scoped package');
+        }
+        return { kind, prefix, cache, installRoot, packageRoot, outerRoot: outerPath,
+            launchEntry: resolve(input.launchEntry), outerPackage, request };
+    }
+    catch {
+        return unsupported('installation metadata is unavailable');
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/application-update/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/application-update/discovery.ts"],"names":[],"mappings":"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"}

package/dist/application-update/helper.d.ts

@@ -0,0 +1,57 @@
+import { type AddressInfo } from 'node:net';
+export interface HelperPlan {
+    installation: {
+        kind: 'global' | 'npx';
+        prefix: string;
+        cache: string;
+        installRoot: string;
+        packageRoot: string;
+        outerRoot: string;
+        launchEntry: string;
+        outerPackage: '@wjarka/cezarion' | 'cezarion';
+        request: string;
+    };
+    targetVersion: string;
+    oldVersion: string;
+    recovery: string;
+    recoveryPackage?: string;
+    binLinks?: string;
+    recordPath: string;
+    oldPid: number;
+    nodeExecutable: string;
+    nodeArgs: string[];
+    cliArgs: string[];
+    cwd: string;
+    repoRoot: string;
+    host: string;
+    port: number;
+    npmBin: string;
+    claimId: string;
+}
+/** Only a listening TCP server can supply the private restart destination. */
+export declare function restartEndpoint(address: AddressInfo | string | null): Pick<HelperPlan, 'host' | 'port'>;
+export declare function restartHealthUrl(endpoint: Pick<HelperPlan, 'host' | 'port'>): string;
+/** A private loopback probe must not use Node's environment-proxied global agent. */
+export declare function requestRestartHealth(endpoint: Pick<HelperPlan, 'host' | 'port'>, signal: AbortSignal): Promise<{
+    version?: string;
+    repoRoot?: string;
+} | undefined>;
+export interface RestartIO {
+    waitForOldExit(): Promise<void>;
+    promote(): Promise<void>;
+    validateOriginal(): Promise<void>;
+    launch(): Promise<void>;
+    verifyHealth(): Promise<void>;
+    reapReplacement(): Promise<void>;
+    restore(): Promise<void>;
+    launchPrevious(): Promise<void>;
+    reportSuccess(): Promise<void>;
+    reportFailure(rollbackFailed: boolean): Promise<void>;
+    assertOwned?(): Promise<void>;
+}
+/** Only the helper owns the promotion transaction. Rollback waits for its child to exit. */
+export declare function runRestartWorkflow(io: RestartIO): Promise<void>;
+export declare function manualRepairCommand(installation: Pick<HelperPlan['installation'], 'kind' | 'prefix' | 'installRoot' | 'outerPackage'>, version: string): string;
+export declare function promoteOriginal(plan: HelperPlan, npxLockAlreadyHeld?: boolean, signal?: AbortSignal): Promise<void>;
+export declare function restoreOriginal(plan: HelperPlan, assertOwned?: () => Promise<void>): Promise<void>;
+export declare function runHelper(plan: HelperPlan, onArmed?: () => void): Promise<void>;