@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/acp/managedRuntime.js

@@ -0,0 +1,314 @@
+/** Bundled release certification is the trust root; writable receipts never authorize a runtime. */
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, readFile, readdir, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+import { inside, assertSafeAgentId, assertSafePackageName } from './builds/model.js';
+import { nodeVersionOf } from './builds/nodeGate.js';
+import { expectedPatchedFiles, patchDigest, verifyPatchedFiles } from './managedPatches.js';
+import { managedRuntimePolicies, packagePatches, patchAssetRoot, validatePackagePatch, validatePatchPath } from './patchAssets.js';
+export const REQUIRED_RUNTIME_CHECKS = ['initialize', 'ordinary-input', 'permissions', 'images-settings', 'parallel-subagents', 'background-reconnect', 'next-append', 'next-button', 'stop', 'cached-resume', 'legacy-migration', 'explicit-load', 'replay', 'install-gates', 'platform'];
+const hashPattern = /^[a-f0-9]{64}$/;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function requireThat(condition, message) {
+    if (!condition)
+        throw new Error(`Managed runtime release: ${message}`);
+}
+function exactVersion(value) { return typeof value === 'string' && semver.valid(value) === value && semver.prerelease(value) === null; }
+export function managedRuntimeFor(agent, policies = managedRuntimePolicies) {
+    const found = policies.filter(policy => policy.agent === agent);
+    requireThat(found.length <= 1, 'duplicate agent policy');
+    return found[0];
+}
+export function assertRuntimeRequest(policy, name, version) {
+    assertSafeAgentId(policy.agent);
+    assertSafePackageName(policy.package);
+    validatePatchPath(policy.release);
+    requireThat(exactVersion(policy.version) && policy.ignore_scripts === true, 'invalid exact version or script policy');
+    requireThat(Array.isArray(policy.required_patches) && policy.required_patches.length > 0 && policy.required_patches.every(id => typeof id === 'string' && id.length > 0) && new Set(policy.required_patches).size === policy.required_patches.length, 'invalid required patches');
+    requireThat(name === policy.package && version === policy.version, `only certified ${policy.package}@${policy.version} may be installed`);
+}
+/**
+ * Reject aliases in every component; use nonblocking nofollow opens so a FIFO cannot hang
+ * verification. Root-owned system symlinks (`/var -> /private/var` on macOS, in front of every
+ * per-user tmpdir) are crossed, not refused: a root-owned link to a root-owned, non-group-writable
+ * directory is not plantable by the running user. Every user-owned symlink is still refused.
+ */
+async function ownedFile(filename) {
+    const full = path.resolve(filename);
+    let current = path.parse(full).root;
+    const systemSymlink = async (uid) => {
+        if (uid !== 0 || process.getuid?.() === 0)
+            return false;
+        try {
+            const target = await realpath(current);
+            const stat = await lstat(target);
+            return stat.isDirectory() && stat.uid === 0 && (stat.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const part of full.slice(current.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        const info = await lstat(current);
+        requireThat(!info.isSymbolicLink() || (await systemSymlink(info.uid)), 'symlink in runtime path');
+    }
+    const file = await open(full, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!(await file.stat()).isFile()) {
+        await file.close();
+        throw new Error('Managed runtime requires a regular file');
+    }
+    return file;
+}
+async function readReleaseAsset(relative, assets) {
+    validatePatchPath(relative);
+    const base = assets.assetRoot ?? patchAssetRoot;
+    const handle = await ownedFile(inside(base instanceof URL ? fileURLToPath(base) : base, relative));
+    try {
+        requireThat((await handle.stat()).size <= 8 * 1024 * 1024, 'manifest too large');
+        return JSON.parse(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function loadRuntimeRelease(policy, assets = {}) {
+    assertRuntimeRequest(policy, policy.package, policy.version);
+    return validateRuntimeRelease(await readReleaseAsset(policy.release, assets), policy, assets);
+}
+function validateRuntimeRelease(r, policy, assets, retained = false) {
+    assertRuntimeRequest(policy, policy.package, policy.version);
+    requireThat(r?.schema === 1 && typeof r.id === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(r.id), 'invalid schema/id');
+    requireThat(r.package === policy.package && r.version === policy.version, 'policy/package/version mismatch');
+    requireThat(typeof r.integrity === 'string' && /^sha512-[A-Za-z0-9+/]{86}==$/.test(r.integrity), 'invalid archive integrity');
+    requireThat(r.bin && typeof r.bin.name === 'string' && r.bin.name.length > 0, 'invalid bin');
+    validatePatchPath(r.bin.path);
+    requireThat(r.bin.args === undefined || (Array.isArray(r.bin.args) && r.bin.args.every(arg => typeof arg === 'string' && !arg.includes('\0'))), 'invalid static argv');
+    requireThat(r.agentInfo && typeof r.agentInfo.name === 'string' && r.agentInfo.name.length > 0 && exactVersion(r.agentInfo.version), 'invalid agent identity');
+    requireThat(r.node && typeof r.node.range === 'string' && semver.validRange(r.node.range), 'invalid Node range');
+    requireThat(Array.isArray(r.historyVersions) && r.historyVersions.includes(r.version) && r.historyVersions.every(exactVersion) && new Set(r.historyVersions).size === r.historyVersions.length, 'invalid history versions');
+    requireThat(same(r.patches, policy.required_patches), 'ordered required patches mismatch');
+    requireThat(r.files && typeof r.files === 'object' && !Array.isArray(r.files) && Object.keys(r.files).length > 0, 'missing trusted files');
+    for (const [file, hash] of Object.entries(r.files)) {
+        validatePatchPath(file);
+        requireThat(typeof hash === 'string' && hashPattern.test(hash), 'invalid trusted file digest');
+    }
+    requireThat(r.files['package.json'] && r.files[r.bin.path], 'manifest and executable must be trusted files');
+    requireThat(r.capabilities?.cachedReconnect === 'resume' && same(r.capabilities.steering, ['next']) && r.capabilities.subagents === true, 'invalid capabilities');
+    const c = r.certification;
+    requireThat(c && typeof c.suite === 'string' && c.suite.length > 0 && Array.isArray(c.checks) && Array.isArray(c.platforms), 'missing certification');
+    requireThat(c.checks.length === REQUIRED_RUNTIME_CHECKS.length && new Set(c.checks.map(v => v.name)).size === c.checks.length && REQUIRED_RUNTIME_CHECKS.every(name => c.checks.some(v => v.name === name)), 'incomplete or duplicate required checks');
+    requireThat(c.checks.every(v => ['PASS', 'NOT_PASS'].includes(v.status) && hashPattern.test(v.evidenceSha256)), 'invalid certification check status');
+    requireThat(c.platforms.every(v => typeof v.platform === 'string' && typeof v.arch === 'string' && ['PASS', 'NOT_PASS'].includes(v.status) && hashPattern.test(v.evidenceSha256)) && new Set(c.platforms.map(v => `${v.platform}/${v.arch}`)).size === c.platforms.length, 'invalid platform records');
+    requireThat(c.platforms.some(v => v.platform === process.platform && v.arch === process.arch), 'platform record missing');
+    requireThat(r.runtimeTools === undefined || Array.isArray(r.runtimeTools), 'invalid runtime tools');
+    const tools = r.runtimeTools ?? [];
+    requireThat(new Set(tools.map(v => `${v.package?.name ?? r.package}/${v.platform}/${v.arch}/${v.path}`)).size === tools.length, 'duplicate runtime tools');
+    for (const tool of tools) {
+        validatePatchPath(tool.path);
+        if (tool.package !== undefined) {
+            requireThat(tool.package && typeof tool.package.name === 'string' && typeof tool.package.version === 'string' && semver.valid(tool.package.version) === tool.package.version, 'invalid exact tool package identity');
+            assertSafePackageName(tool.package.name);
+        }
+        const primary = tool.package === undefined || tool.package.name === r.package;
+        requireThat(typeof tool.platform === 'string' && typeof tool.arch === 'string' && hashPattern.test(tool.sha256) && (!primary || r.files[tool.path] === tool.sha256) && c.platforms.some(v => v.platform === tool.platform && v.arch === tool.arch), 'tool must match a trusted digest and declared platform');
+    }
+    if (retained)
+        requireThat(typeof r.patchDigest === 'string' && hashPattern.test(r.patchDigest), 'retained release requires trusted patch digest');
+    else {
+        const digest = patchDigest(runtimeRecipes(policy, r, assets.recipes));
+        requireThat(r.patchDigest === undefined || r.patchDigest === digest, 'release patch digest disagrees with bundled recipes');
+    }
+    return r;
+}
+export function runtimeRecipes(policy, release, recipes = packagePatches) {
+    const selected = recipes.filter(recipe => recipe.package === policy.package && recipe.versions?.includes(policy.version));
+    requireThat(same(selected.map(v => v.id), policy.required_patches), 'missing or unordered exact patch recipe');
+    for (const recipe of selected) {
+        validatePackagePatch(recipe);
+        requireThat(recipe.bin === undefined || recipe.bin === release.bin.name, 'patch bin disagrees with release');
+    }
+    for (const [qualified, hash] of Object.entries(expectedPatchedFiles(selected))) {
+        requireThat(release.files[qualified.slice(policy.package.length + 1)] === hash, 'patch digest disagrees with trusted release files');
+    }
+    return selected;
+}
+/** Reverse the declared edits to derive trusted pristine hashes, without trusting package metadata. */
+function pristineFiles(release, recipes) {
+    const files = { ...release.files };
+    for (const recipe of [...recipes].reverse()) {
+        for (const asset of recipe.assets ?? [])
+            delete files[asset.target];
+        for (const edit of [...recipe.edits].reverse()) {
+            requireThat(files[edit.file] === edit.after_sha256 && hashPattern.test(edit.before_sha256), 'inconsistent patch hash chain');
+            files[edit.file] = edit.before_sha256;
+        }
+    }
+    return files;
+}
+export async function verifyRuntimeTree(options) {
+    const r = await loadRuntimeRelease(options.policy, options);
+    return verifyReleaseTree(options, r);
+}
+async function verifyReleaseTree(options, r) {
+    const pkg = inside(path.join(options.treeRoot, 'node_modules'), r.package);
+    const files = options.pristine ? pristineFiles(r, runtimeRecipes(options.policy, r, options.recipes)) : r.files;
+    await verifyPatchedFiles(pkg, files);
+    // Extra executable code or links must not survive a cache adoption, even with matching package.json.
+    const actual = [];
+    const walk = async (dir, prefix = '') => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const rel = prefix + entry.name;
+            if (entry.isDirectory())
+                await walk(path.join(dir, entry.name), rel + '/');
+            else {
+                requireThat(entry.isFile(), 'non-regular runtime asset');
+                actual.push(rel);
+            }
+        }
+    };
+    await walk(pkg);
+    requireThat(same(actual.sort(), Object.keys(files).sort()), 'unexpected or missing runtime files');
+    const metadata = JSON.parse(await readFile(path.join(pkg, 'package.json'), 'utf8'));
+    requireThat(metadata.name === r.package && metadata.version === r.version && metadata.bin?.[r.bin.name] === r.bin.path, 'package identity/bin mismatch');
+    for (const tool of r.runtimeTools ?? []) {
+        if (tool.platform !== process.platform || tool.arch !== process.arch)
+            continue;
+        const toolPackage = tool.package ?? { name: r.package, version: r.version };
+        const toolDir = inside(path.join(options.treeRoot, 'node_modules'), toolPackage.name);
+        const manifest = await ownedFile(path.join(toolDir, 'package.json'));
+        try {
+            const identity = JSON.parse(await manifest.readFile('utf8'));
+            requireThat(identity.name === toolPackage.name && identity.version === toolPackage.version, 'runtime tool package identity mismatch');
+        }
+        finally {
+            await manifest.close();
+        }
+        // External tools are authenticated by this explicit record, not by a claim about their whole package.
+        await verifyPatchedFiles(toolDir, { [tool.path]: tool.sha256 });
+        const handle = await ownedFile(inside(toolDir, tool.path));
+        try {
+            if (options.prepareTools)
+                await handle.chmod(0o755);
+            requireThat(process.platform === 'win32' || ((await handle.stat()).mode & 0o111) !== 0, `runtime tool not executable: ${tool.path}`);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return r;
+}
+export async function verifyManagedRuntime(options) {
+    const release = await loadRuntimeRelease(options.policy, options);
+    await verifyReleaseBuild(options, release, patchDigest(runtimeRecipes(options.policy, release, options.recipes)));
+}
+/** Explicit recorded bindings/rollback only. Every historical authority is bundled and listed, never a writable receipt. */
+export async function verifyRecordedManagedRuntime(options) {
+    const active = await loadRuntimeRelease(options.policy, options);
+    if (options.build.runtimeReleaseId === active.id) {
+        await verifyReleaseBuild(options, active, patchDigest(runtimeRecipes(options.policy, active, options.recipes)));
+        return;
+    }
+    const paths = options.policy.retained_releases ?? [];
+    requireThat(Array.isArray(paths) && new Set(paths).size === paths.length && !paths.includes(options.policy.release), 'duplicate or active retained release path');
+    const ids = new Set([active.id]);
+    let match;
+    for (const relative of paths) {
+        const release = await readReleaseAsset(relative, options);
+        requireThat(release?.schema === 1 && typeof release.id === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(release.id) && !ids.has(release.id), 'invalid, duplicate or active retained release identity');
+        ids.add(release.id);
+        if (release.id === options.build.runtimeReleaseId)
+            match = { release, path: relative };
+    }
+    requireThat(match, 'recorded release is not explicitly retained');
+    const policy = { agent: options.policy.agent, package: match.release.package, version: match.release.version, release: match.path, required_patches: match.release.patches, ignore_scripts: true };
+    const release = validateRuntimeRelease(match.release, policy, options, true);
+    requireThat(release.package !== options.policy.package || semver.lte(release.version, options.policy.version), 'retained release is a future version');
+    await verifyReleaseBuild({ ...options, policy }, release, release.patchDigest);
+}
+async function verifyReleaseBuild(options, release, digest) {
+    const { policy, build } = options;
+    requireThat(release.certification.checks.length === REQUIRED_RUNTIME_CHECKS.length && release.certification.checks.every(v => v.status === 'PASS'), 'release certification is NOT_PASS');
+    requireThat(release.certification.platforms.some(v => v.platform === process.platform && v.arch === process.arch && v.status === 'PASS'), 'platform is NOT_PASS');
+    assertRuntimeRequest(policy, build.package ?? '', build.version);
+    await verifyReleaseTree({ ...options, treeRoot: inside(options.storeRoot, build.dir), pristine: false }, release);
+    requireThat(build.agentId === policy.agent && build.runtimeReleaseId === release.id, 'build release identity mismatch');
+    requireThat(build.kind === 'npm-patched' && build.patchDigest === digest && same(build.patches, release.patches), 'build patch identity mismatch');
+    requireThat(build.launch.entry === `node_modules/${release.package}/${release.bin.path}` && build.launch.runtime === 'node', 'build executable/dispatcher mismatch');
+    requireThat(same(build.launch.args, release.bin.args ?? []), 'build static argv mismatch');
+    const nodeVersion = await nodeVersionOf(options.nodePath);
+    requireThat(semver.satisfies(nodeVersion, release.node.range, { includePrerelease: false }), `Node ${nodeVersion} outside ${release.node.range}`);
+    if (options.initialize)
+        await initializeProbe(build, options.storeRoot, options.nodePath, release);
+}
+/** One initialize only, no credentials or user HOME, bounded streams/time, awaited process cleanup. */
+async function initializeProbe(build, storeRoot, nodePath, release) {
+    const home = await mkdtemp(path.join(tmpdir(), 'runtime-probe-'));
+    try {
+        await new Promise((resolve, reject) => {
+            const dir = inside(storeRoot, build.dir);
+            const child = spawn(nodePath, [inside(dir, build.launch.entry), ...build.launch.args], {
+                cwd: home, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+                env: { PATH: [path.dirname(nodePath), ...(build.launch.pathDirs ?? []).map(p => inside(dir, p)), process.env.PATH ?? ''].join(path.delimiter), HOME: home, USERPROFILE: home, APPDATA: home, LOCALAPPDATA: home, XDG_CONFIG_HOME: home, XDG_CACHE_HOME: home, TMPDIR: home, TEMP: home, TMP: home, ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}) },
+            });
+            let output = '';
+            let bytes = 0;
+            let stderrBytes = 0;
+            let response = false;
+            let failure;
+            const fail = (message) => { failure ??= new Error(`Managed runtime initialize: ${message}`); child.kill('SIGKILL'); };
+            const timeout = setTimeout(() => fail('timed out'), 30_000);
+            child.on('error', error => { failure ??= error; });
+            child.stdin.on('error', () => { });
+            child.stderr.on('data', (data) => { stderrBytes += data.length; if (stderrBytes > 1024 * 1024)
+                fail('stderr limit exceeded'); });
+            child.stdout.on('data', (data) => {
+                bytes += data.length;
+                if (bytes > 1024 * 1024) {
+                    fail('stdout limit exceeded');
+                    return;
+                }
+                output += data.toString('utf8');
+                let end;
+                while ((end = output.indexOf('\n')) >= 0) {
+                    const line = output.slice(0, end);
+                    output = output.slice(end + 1);
+                    try {
+                        requireThat(!response, 'extra initialize response');
+                        const msg = JSON.parse(line);
+                        const result = msg.result;
+                        requireThat(msg.jsonrpc === '2.0' && msg.id === 'axom-runtime-initialize' && !Object.hasOwn(msg, 'error') && !Object.hasOwn(msg, 'method') && result?.protocolVersion === 1, 'invalid correlated initialize result');
+                        requireThat(result.agentInfo?.name === release.agentInfo.name && result.agentInfo?.version === release.agentInfo.version, 'initialize agent identity mismatch');
+                        requireThat(result._meta?.axom?.releaseId === release.id && result._meta?.axom?.cachedReconnect === 'resume', 'initialize release/resume mismatch');
+                        requireThat(result.agentCapabilities?.loadSession === true && result.agentCapabilities?.sessionCapabilities?.resume && typeof result.agentCapabilities.sessionCapabilities.resume === 'object' && !Array.isArray(result.agentCapabilities.sessionCapabilities.resume), 'missing resume capability');
+                        requireThat(result._meta?.steering?.supported === true && same(result._meta.steering.timings, ['next']), 'missing next capability');
+                        response = true;
+                        child.stdin.end();
+                        // Await graceful EOF cleanup within the same overall deadline. Native agents may
+                        // flush telemetry before exiting; a second, shorter deadline can kill a healthy one.
+                    }
+                    catch (error) {
+                        fail(error.message);
+                    }
+                }
+            });
+            child.once('close', (code) => {
+                clearTimeout(timeout);
+                if (!failure && (!response || output.trim() || code !== 0))
+                    failure = new Error('Managed runtime initialize: incomplete response or startup failure');
+                if (failure)
+                    reject(failure);
+                else
+                    resolve();
+            });
+            child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 'axom-runtime-initialize', method: 'initialize', params: { protocolVersion: 1, clientInfo: { name: 'axom-runtime-check', version: '1.0.0' }, clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true } } }) + '\n');
+        });
+    }
+    finally {
+        await rm(home, { recursive: true, force: true });
+    }
+}

package/dist/workstation/acp/outbox.js

@@ -0,0 +1,330 @@
+/**
+ * ## Subagent relations bypass the window (fix round 1, spec §5.6)
+ *
+ * The server holds back its applied watermark — so its acks — at the first child frame whose subagent relation (`subagent_spawned`,
+ * the server's `TimelineEvent.SubagentSpawned`) it has not received yet (`noteApplied` capped at `nativePendingBefore - 1`,
+ * `ExternalAgentEventApplier.kt`). Every later frame then counts against the window; if the relation comes 256 or more frames after
+ * that first orphan child frame, a window that held it back would stall the session for good (the server waits 30 s, poisons, the
+ * reopen repeats it). So:
+ *
+ * - **producing**: while a child frame whose relation is not recorded yet is unacknowledged ({@link orphanOutstanding}), the record
+ *   loop may run past the window, so the relation can be folded at all. Whatever the branch, this life never holds more than
+ *   {@link RELATION_WAIT_EVENTS} / {@link RELATION_WAIT_BYTES} (1024 frames / 32 MiB) unacknowledged — pinned entries included — plus
+ *   the frames of the one record being folded: that is the daemon's memory bound per session;
+ * - **sending**: once a relation that resolves such a child (a *resolving* relation) is recorded, it and every entry before it stop
+ *   counting against either window ({@link pinnedThrough}): the sender takes them past the window, in seq order (sending the
+ *   relation first would make the server drop the lower seqs as duplicates); the socket gate still applies. They must keep not
+ *   counting after they are sent: the server applied them but wasted its acks while capped (each ack attempt resets its 32-event
+ *   count), so its next ack needs up to 31 more applied frames — a window still full of them would deadlock there. They leave the
+ *   outbox with that ack. A relation that resolves nothing recorded is not what the server waits for and keeps to the window
+ *   (sending past it could overflow a parked server's 512-frame hold-off).
+ *
+ * ## Residual (documented, not fixed)
+ *
+ * While the producing window is full — a server parked on an approval with ≥ 256 root frames held, a connection that is down, an
+ * applier that never acknowledges — the record loop folds nothing: a steer or config RPC waits for the processor's reply and can
+ * time out on the server; an `agent_interrupt` note is folded (and the `session/cancel` written) only once the server unparks.
+ */
+/** Unacknowledged events per session (spec §5.6, `W_EVT`). `ACK_EVERY_EVENTS(32) < W_EVT ≤ HOLD_OFF_CAPACITY(512)`. */
+export const SESSION_WINDOW_EVENTS = 256;
+/** Unacknowledged bytes per session (spec §5.6): a few huge frames cannot hog the window. */
+export const SESSION_WINDOW_BYTES = 8 * 1024 * 1024;
+/** How far production may run past the window while a recorded child frame still waits for its relation (bounds memory). */
+export const RELATION_WAIT_EVENTS = 4 * SESSION_WINDOW_EVENTS;
+export const RELATION_WAIT_BYTES = 4 * SESSION_WINDOW_BYTES;
+/** A frame carrying a subagent relation (the server's `SubagentSpawned`): it bypasses the session window. */
+export function isRelationFrame(frame) {
+    return frame.t === 'agent_event' && frame.eventName === 'subagent_spawned';
+}
+/**
+ * `src.i` of an outbox entry no record produced: a frame this daemon numbered itself (a degraded session's failed `turn_done`,
+ * `src.o` = the last record folded before it) or one imported from a legacy journal (`src.o` = 0). A replay never reproduces it
+ * (T21 skips it when comparing). Far above any per-record frame index.
+ */
+export const DAEMON_FRAME_INDEX = 1 << 24;
+/**
+ * Connection epoch of an entry that may have reached the server on an earlier connection (or in an earlier daemon life): it is not
+ * sent again until the server reopens the ref and says how far it got ({@link SessionOutbox.resendAll} after an `ack` of the open's
+ * `resumeFromSeq`) — resending a frame the server already applied could, for a `turn_done`, end a newer turn (analysis B §3.1).
+ */
+export const SENT_EARLIER = -1;
+const frameBytes = (frame) => Buffer.byteLength(JSON.stringify(frame));
+export function isOutboxTail(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { seq, src } = value;
+    return Number.isSafeInteger(seq) && typeof src === 'object' && src !== null &&
+        Number.isSafeInteger(src.o) && Number.isSafeInteger(src.i);
+}
+export class SessionOutbox {
+    store;
+    items = [];
+    committed;
+    highestSeq = 0;
+    ownEvents = 0;
+    ownBytes = 0;
+    chain = Promise.resolve();
+    roomWaiters = new Set();
+    listeners = new Set();
+    stopped = false;
+    /** Children whose relation frame this outbox recorded. */
+    related = new Set();
+    /** Seq of the latest resolving relation: entries at or below it count against neither window (file comment). */
+    pinned = 0;
+    isRelated;
+    /**
+     * `isRelated`: whether the session already knows a child's relation from elsewhere (the processor's relation graph — a relation
+     * recorded by an earlier life, or replayed by a load). Without it only relations this outbox recorded count.
+     */
+    constructor(store, init = {}) {
+        this.store = store;
+        this.isRelated = init.isRelated ?? (() => false);
+        this.committed = isOutboxTail(init.committedTail) ? { seq: init.committedTail.seq, src: { ...init.committedTail.src } } : null;
+        this.highestSeq = this.committed?.seq ?? 0;
+        for (const record of init.leftovers ?? []) {
+            // Read back past the watermark only; a record at or below it is acknowledged (truncation is by whole segments).
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes: frameBytes(record.frame), leftover: true,
+                ...this.classify(record.seq, record.frame), sentOn: SENT_EARLIER });
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+    }
+    /**
+     * Resolving relation / orphan frame, in record order (a relation relates its child for every later frame). An orphan is a frame
+     * the server retains until a relation it has not received: a child frame (`acpSessionId`) whose child is unrelated, and — Task
+     * 22 — a `subagent_state_update` (any origin) naming an unrelated child (`payload.subagentSessionId`): the server's
+     * `receiveNativeEventLocked` holds it, and with it its acks, until that child's `subagent_spawned` exactly as it holds a child
+     * frame. The state update's own child is the key: a root-origin one would otherwise not be an orphan at all, its relation would
+     * keep to the window, and the session would stall where Task 20 fixed it for child frames.
+     */
+    classify(seq, frame) {
+        const unrelated = (child) => child !== undefined && !this.related.has(child) && !this.isRelated(child) ? child : undefined;
+        const origin = frame.t === 'agent_event' && typeof frame.acpSessionId === 'string' ? frame.acpSessionId : undefined;
+        const stateChild = frame.t === 'agent_event' && frame.eventName === 'subagent_state_update'
+            ? frame.payload?.subagentSessionId
+            : undefined;
+        const orphanOf = unrelated(typeof stateChild === 'string' ? stateChild : undefined) ?? unrelated(origin);
+        let resolving = false;
+        if (isRelationFrame(frame)) {
+            const child = frame.payload?.subagentSessionId;
+            if (typeof child === 'string') {
+                resolving = this.items.some((item) => item.orphanOf === child);
+                this.related.add(child);
+                if (resolving)
+                    this.pinned = Math.max(this.pinned, seq);
+            }
+        }
+        return { resolving, ...(orphanOf !== undefined ? { orphanOf } : {}) };
+    }
+    /** Entries at or below this seq count against neither window (the latest resolving relation; 0: none). */
+    get pinnedThrough() { return this.pinned; }
+    /** An unacknowledged child frame whose relation is still not recorded: the server is (likely) holding its acks for it. */
+    orphanOutstanding() {
+        return this.items.some((item) => item.orphanOf !== undefined && !this.related.has(item.orphanOf) && !this.isRelated(item.orphanOf));
+    }
+    /** Highest seq this outbox ever held (entries, or the acknowledged watermark): a new life numbers after it (§5.5). */
+    get lastSeq() { return this.highestSeq; }
+    /** The acknowledged watermark (`committedTail`), `null` before the first truncating ack. */
+    get committedTail() { return this.committed; }
+    /** Unacknowledged entries, in seq order. */
+    get pending() { return this.items; }
+    /** Unacknowledged entries appended by this life (the producing window), past {@link pinnedThrough}. */
+    get backlog() {
+        if (this.pinned === 0)
+            return { events: this.ownEvents, bytes: this.ownBytes };
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items)
+            if (!item.leftover && item.seq > this.pinned) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        return { events, bytes };
+    }
+    /**
+     * Entries sent on connection `epoch` and not acknowledged (the sending window). Entries at or below {@link pinnedThrough} are
+     * sent past the window either way (the sender bypasses it for them); once sent they count only when `pinnedCountsWhenSent` —
+     * a server that acknowledges as soon as the relation releases its cap (`AGENT_WIRE_RELATION_ACK_VERSION`, Task 22). An older
+     * server wastes its acks while capped, so its first ack after the relation can need up to 31 more applied frames: counting the
+     * pinned ones there would deadlock right after the relation (fix round 1 of Task 20).
+     */
+    inflight(epoch, pinnedCountsWhenSent = false) {
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items) {
+            if (item.sentOn === epoch && (pinnedCountsWhenSent || item.seq > this.pinned)) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        }
+        return { events, bytes };
+    }
+    /** Called whenever there may be something new to send (an append, an ack opening the window, a resend). */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    changed() { for (const listener of [...this.listeners])
+        listener(); }
+    run(op) {
+        const result = this.chain.then(op);
+        this.chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** Waits for every stream operation queued so far. */
+    flush() { return this.chain; }
+    /**
+     * Record frames before they are sent. Resolves once they are durable; rejects when the stream refused them (the caller degrades
+     * the session — a frame that could not be recorded is not sent either).
+     */
+    append(frames) {
+        if (frames.length === 0)
+            return this.chain;
+        return this.run(async () => {
+            const entries = frames.map((f) => ({ seq: f.seq, src: { o: f.src.o, i: f.src.i }, frame: { ...f.frame } }));
+            const { first } = await this.store.append(entries);
+            entries.forEach((entry, index) => {
+                const bytes = frameBytes(entry.frame);
+                this.items.push({ o: first + index, seq: entry.seq, src: entry.src, frame: entry.frame, bytes, leftover: false, ...this.classify(entry.seq, entry.frame), sentOn: null });
+                this.highestSeq = Math.max(this.highestSeq, entry.seq);
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            });
+            this.wakeRoom(); // a resolving relation unpins the producing window
+            this.changed();
+        });
+    }
+    /**
+     * The server applied everything through `throughSeq` (`agent_event_ack`, or an open's `resumeFromSeq`): forget those entries and
+     * truncate the stream through the last of them, persisting `{seq, src}` of that entry as the watermark. Nothing held at or below
+     * it: nothing changes. A failed commit is reported (`onError`) — the entries are acknowledged either way; the stream keeps them
+     * until a later commit passes them.
+     */
+    ack(throughSeq, onError) {
+        return this.run(async () => {
+            let k = -1;
+            for (let i = 0; i < this.items.length && this.items[i].seq <= throughSeq; i++)
+                k = i;
+            if (k < 0)
+                return;
+            const last = this.items[k];
+            const removed = this.items.splice(0, k + 1);
+            for (const item of removed)
+                if (!item.leftover) {
+                    this.ownEvents -= 1;
+                    this.ownBytes -= item.bytes;
+                }
+            this.committed = { seq: last.seq, src: { ...last.src } };
+            this.wakeRoom();
+            this.changed();
+            try {
+                await this.store.commit({ outbox: { through: last.o, tail: { seq: last.seq, src: { ...last.src } } } });
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        });
+    }
+    /**
+     * A processor checkpoint at raw `offset`, and raw truncation through it (the keeper refuses anything past it) unless `truncate` is
+     * false (a marker checkpoint, Task 21).
+     */
+    commitCheckpoint(offset, blob, truncate = true) {
+        return this.run(async () => {
+            await this.store.commit({ checkpoint: { offset, blob }, ...(truncate ? { rawThrough: offset } : {}) });
+        });
+    }
+    /**
+     * The session re-attached to keeper-acp after its connection was lost (Task 21): the stream is the truth again. An append whose
+     * reply was lost may have landed (it is in `leftovers` now) or not (it is gone, and the record loop folds its record again). The
+     * entries are replaced by what the stream holds past its watermark; an entry this object already had keeps whether (and on which
+     * connection) it was sent and whether an earlier life left it; one it never saw was never sent. Call it with no stream operation
+     * in flight ({@link flush} first). Listeners and room waiters are kept.
+     */
+    rebase(init) {
+        const previous = new Map(this.items.map((item) => [item.seq, item]));
+        this.items.length = 0;
+        this.related.clear();
+        this.pinned = 0;
+        this.ownEvents = 0;
+        this.ownBytes = 0;
+        if (isOutboxTail(init.committedTail) && (this.committed === null || init.committedTail.seq >= this.committed.seq)) {
+            this.committed = { seq: init.committedTail.seq, src: { ...init.committedTail.src } };
+        }
+        this.highestSeq = Math.max(this.highestSeq, this.committed?.seq ?? 0);
+        for (const record of init.leftovers) {
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            const before = previous.get(record.seq);
+            const leftover = before?.leftover ?? false;
+            const bytes = frameBytes(record.frame);
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes, leftover,
+                ...this.classify(record.seq, record.frame), sentOn: before ? before.sentOn : null });
+            if (!leftover) {
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            }
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+        this.wakeRoom();
+        this.changed();
+    }
+    /** Mark every unacknowledged entry unsent: the sender resends them in order (a reopen's replay, after the ack of its watermark). */
+    resendAll() {
+        for (const item of this.items)
+            item.sentOn = null;
+        this.changed();
+    }
+    /**
+     * A new connection: everything recorded so far — sent on an earlier connection or produced while none was bound — is held until
+     * the server reopens the ref and says how far it got ({@link SENT_EARLIER}); what is recorded from now on is sent at once. (The
+     * journal's semantics: frames produced while unbound were replayed by the reopen, never sent on their own.)
+     */
+    connectionChanged() {
+        for (const item of this.items)
+            item.sentOn = SENT_EARLIER;
+    }
+    /** The first entry never sent (the sender's next candidate), in seq order. */
+    nextUnsent() {
+        return this.items.find((item) => item.sentOn === null);
+    }
+    /** Resolves when this life's unacknowledged backlog is below the window (immediately once {@link stopWaiting} ran). */
+    room() {
+        if (this.hasRoom())
+            return undefined;
+        return new Promise((resolve) => { this.roomWaiters.add(resolve); });
+    }
+    hasRoom() {
+        if (this.stopped)
+            return true;
+        // A hard bound on everything this life holds unacknowledged, pinned or not: chained resolving relations each reset `backlog`,
+        // but pinned entries leave memory only with an ack.
+        if (this.ownEvents >= RELATION_WAIT_EVENTS || this.ownBytes >= RELATION_WAIT_BYTES)
+            return false;
+        const { events, bytes } = this.backlog;
+        if (events < SESSION_WINDOW_EVENTS && bytes < SESSION_WINDOW_BYTES)
+            return true;
+        // Past the window only while a relation is awaited: the server cannot acknowledge before it, so it must be folded.
+        return this.orphanOutstanding();
+    }
+    wakeRoom() {
+        if (!this.hasRoom())
+            return;
+        for (const resolve of [...this.roomWaiters])
+            resolve();
+        this.roomWaiters.clear();
+    }
+    /** The session is closing or degraded: nobody waits for room any more. */
+    stopWaiting() {
+        this.stopped = true;
+        this.wakeRoom();
+    }
+}
+/** An outbox store over a transport session (`acp.outbox.append` / `acp.commit`). */
+export function transportOutboxStore(transport, sessionKey) {
+    return {
+        append: (entries) => transport.appendOutbox(sessionKey, entries),
+        commit: (params) => transport.commit(sessionKey, params),
+    };
+}