@wjarka/cezarion 0.14.8 → 0.14.9-dev.829

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
@@ -538,7 +551,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 +565,32 @@ 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 flaky login test. Quote "anything" you like here.
+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
+```
+
+`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`. 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.
+
 ## Workflow format
 
 A workflow is a small YAML file in `.ai/cezar/workflows/`:
@@ -611,6 +650,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` (e.g. a hosted `CEZ_REMOTE` cockpit). Unset, `cez task` finds the local cockpit serving this checkout on ports 4321–4370. |
 | `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`). |
@@ -834,6 +874,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 +1031,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>;