akemon 0.3.3 → 0.3.5

package/README.md

@@ -164,11 +164,34 @@ akemon serve --name my-agent --engine claude
 
 # In another terminal, ask the local software peripheral to work in the repo
 akemon software-agent "Add one focused test and run the relevant test command."
+
+# Review recent software-agent runs
+akemon software-agent-tasks --limit 5
 ```
 
 This is different from `--engine`: engines are replaceable compute, while software agents are external software bodies with their own repo context, skills, tools, and execution loop.
 
-Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+
+Software-agent tasks default to the `akemon serve` workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
+
+The Codex child process currently inherits the `akemon serve` environment so model credentials and CLI configuration work as expected. Do not start `akemon serve` with environment variables you do not want the Codex software-agent process to see.
+
+Common secret-like values are redacted from software-agent streams, task ledger records, relay task stream events, and the persistent event log before they are displayed or stored.
+
+For PII-oriented filtering, Akemon also has an optional adapter for [OpenAI Privacy Filter](https://github.com/openai/privacy-filter). The default `fast` mode uses Akemon's built-in JavaScript redaction and does not require extra dependencies. To use OPF, install the external `opf` Python CLI yourself, then opt in explicitly:
+
+```bash
+akemon privacy-filter --mode fast "OPENAI_API_KEY=sk-..."
+akemon privacy-filter --mode pii --backend opf --device cpu "Alice was born on 1990-01-02."
+akemon privacy-filter --mode strict --backend opf --checkpoint ~/.opf/privacy_filter "Alice ..."
+```
+
+You can also configure OPF with `AKEMON_PRIVACY_FILTER=opf`, `AKEMON_OPF_COMMAND`, `AKEMON_OPF_DEVICE`, `AKEMON_OPF_CHECKPOINT`, `AKEMON_OPF_TIMEOUT_MS`, and `AKEMON_OPF_MAX_INPUT_CHARS`. In `pii` mode, OPF failures fall back to built-in redaction with a warning; in `strict` mode they fail the command.
+
+The software-agent task ledger keeps the most recent 200 task records by default.
+
+The persistent event log rotates automatically at about 10 MB per file and keeps the current `events.jsonl` plus five rotated files.
 
 ## Serve Options
 

package/dist/cli.js

@@ -6,6 +6,8 @@ import { getOrCreateRelayCredentials } from "./config.js";
 import { connectRelay } from "./relay-client.js";
 import { listAgents } from "./list.js";
 import { connect } from "./connect.js";
+import { PrivacyFilterUnavailableError, sanitizeText, } from "./privacy-filter.js";
+import { SoftwareAgentStreamCliRenderer } from "./software-agent-stream-cli.js";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
@@ -18,21 +20,74 @@ function parsePortOption(port) {
     const value = typeof port === "number" ? port : parseInt(String(port || "3000"));
     return Number.isInteger(value) && value > 0 ? value : 3000;
 }
+function clampPositiveInt(value, fallback, max) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(parsed, max);
+}
+function parsePrivacyFilterMode(value) {
+    if (value === "fast" || value === "pii" || value === "strict")
+        return value;
+    console.error("--mode must be one of: fast, pii, strict");
+    process.exit(1);
+}
+function parsePrivacyFilterBackend(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "fast" || value === "opf")
+        return value;
+    console.error("--backend must be one of: fast, opf");
+    process.exit(1);
+}
+function parseSoftwareAgentEnvPolicy(value) {
+    const normalized = (value || "inherit").trim().toLowerCase();
+    if (normalized === "inherit" || normalized === "allowlist")
+        return normalized;
+    console.error("--software-agent-env must be one of: inherit, allowlist");
+    process.exit(1);
+}
+function parseCommaSeparatedCliOption(value) {
+    if (!value)
+        return undefined;
+    const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+    return items.length ? items : undefined;
+}
+function parsePositiveIntCliOption(value, optionName) {
+    if (value === undefined)
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        console.error(`${optionName} must be a positive integer`);
+        process.exit(1);
+    }
+    return parsed;
+}
+function printSoftwareAgentTaskList(tasks) {
+    if (!tasks.length) {
+        console.log("No software-agent tasks found.");
+        return;
+    }
+    for (const task of tasks) {
+        const result = task.result?.success === true ? "ok" : task.result?.success === false ? "error" : "pending";
+        const duration = typeof task.durationMs === "number" ? `${task.durationMs}ms` : "-";
+        const git = task.workdirStatus?.isRepo
+            ? (task.workdirStatus.dirty ? `dirty:${task.workdirStatus.changedFiles?.length || 0}` : "clean")
+            : "no-git";
+        const goal = truncateOneLine(task.envelope?.goal || "", 90);
+        console.log(`${task.taskId}  ${task.status}/${result}  ${duration}  ${git}  ${task.updatedAt || task.startedAt}`);
+        if (goal)
+            console.log(`  ${goal}`);
+    }
+}
+function truncateOneLine(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, Math.max(0, max - 3))}...`;
+}
 async function callLocalOwnerEndpoint(path, opts, init = {}) {
-    const credentials = await getOrCreateRelayCredentials();
-    const port = parsePortOption(opts.port);
-    const headers = {
-        Authorization: `Bearer ${credentials.secretKey}`,
-    };
-    if (init.body !== undefined)
-        headers["Content-Type"] = "application/json";
-    const res = await fetch(`http://127.0.0.1:${port}${path}`, {
-        ...init,
-        headers: {
-            ...headers,
-            ...init.headers,
-        },
-    });
+    const res = await fetchLocalOwnerEndpoint(path, opts, init);
     const text = await res.text();
     let data;
     try {
@@ -47,6 +102,80 @@ async function callLocalOwnerEndpoint(path, opts, init = {}) {
     }
     return data;
 }
+async function fetchLocalOwnerEndpoint(path, opts, init = {}) {
+    const credentials = await getOrCreateRelayCredentials();
+    const port = parsePortOption(opts.port);
+    const headers = {
+        Authorization: `Bearer ${credentials.secretKey}`,
+    };
+    if (init.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    let res;
+    try {
+        res = await fetch(`http://127.0.0.1:${port}${path}`, {
+            ...init,
+            headers: {
+                ...headers,
+                ...init.headers,
+            },
+        });
+    }
+    catch (error) {
+        const cause = error.cause;
+        if (error instanceof TypeError && error.message === "fetch failed" && cause?.message === "bad port") {
+            console.error(`Port ${port} cannot be used for the local akemon serve connection. Choose a different --port.`);
+            process.exit(1);
+        }
+        if (error instanceof TypeError && error.message === "fetch failed") {
+            console.error(`Cannot connect to local akemon serve on port ${port}. Start it with: akemon serve --port ${port}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    return res;
+}
+async function streamLocalOwnerEndpoint(path, opts, body) {
+    const res = await fetchLocalOwnerEndpoint(path, opts, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { error: text };
+        }
+        console.error(data.error || text || `Request failed with HTTP ${res.status}`);
+        process.exit(1);
+    }
+    if (!res.body)
+        return;
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let failed = false;
+    const streamRenderer = new SoftwareAgentStreamCliRenderer();
+    const reader = res.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+            if (streamRenderer.handleLine(line))
+                failed = true;
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim() && streamRenderer.handleLine(buffer))
+        failed = true;
+    if (failed)
+        process.exit(1);
+}
 program
     .name("akemon")
     .description("Agent work marketplace — train your agent, let it work for others")
@@ -75,6 +204,8 @@ program
     .option("--without <modules>", "Disable specific modules (comma-separated: biostate,memory)")
     .option("--script <name>", "Script to load for ScriptModule (default: daily-life)", "daily-life")
     .option("--terminal", "Enable remote terminal access (PTY)")
+    .option("--software-agent-env <policy>", "Software-agent child environment policy: inherit or allowlist", process.env.AKEMON_SOFTWARE_AGENT_ENV_POLICY || "inherit")
+    .option("--software-agent-env-allow <vars>", "Comma-separated extra env vars for software-agent allowlist")
     .option("--relay <url>", "Relay WebSocket URL", RELAY_WS)
     .action(async (opts) => {
     const port = parseInt(opts.port);
@@ -110,6 +241,8 @@ program
         notifyUrl: opts.notify,
         enabledModules,
         scriptName: opts.script,
+        softwareAgentEnvPolicy: parseSoftwareAgentEnvPolicy(opts.softwareAgentEnv),
+        softwareAgentEnvAllowlist: parseCommaSeparatedCliOption(opts.softwareAgentEnvAllow),
     });
     console.log(`\nakemon v${pkg.version}`);
     if (!opts.public) {
@@ -171,12 +304,15 @@ program
     .argument("<goal...>", "Task goal to send to the software agent")
     .option("-p, --port <port>", "Local akemon serve port", "3000")
     .option("-w, --workdir <path>", "Workdir for the software agent (default: serve workdir)")
+    .option("--allow-outside-workdir", "Allow the software agent workdir to be outside the serve workdir")
     .option("--role-scope <scope>", "Role scope: owner|public|order|agent|system", "owner")
     .option("--memory-scope <scope>", "Memory scope: none|public|task|owner", "owner")
     .option("--risk <level>", "Risk level: low|medium|high", "medium")
     .option("--memory-summary <text>", "Pre-filtered memory/context text to include")
+    .option("--session <id>", "Akemon-side context session id for explicit software-agent continuity")
     .option("--deliverable <text>", "Expected output shape")
     .option("--timeout-ms <ms>", "Task timeout in milliseconds")
+    .option("--no-stream", "Disable local streaming and wait for the final response")
     .action(async (goalParts, opts) => {
     const body = {
         goal: goalParts.join(" "),
@@ -186,8 +322,12 @@ program
     };
     if (opts.workdir)
         body.workdir = opts.workdir;
+    if (opts.allowOutsideWorkdir)
+        body.allowOutsideWorkdir = true;
     if (opts.memorySummary)
         body.memorySummary = opts.memorySummary;
+    if (opts.session)
+        body.contextSessionId = opts.session;
     if (opts.deliverable)
         body.deliverable = opts.deliverable;
     if (opts.timeoutMs) {
@@ -198,6 +338,10 @@ program
         }
         body.timeoutMs = timeoutMs;
     }
+    if (opts.stream !== false) {
+        await streamLocalOwnerEndpoint("/self/software-agent/run-stream", opts, body);
+        return;
+    }
     const data = await callLocalOwnerEndpoint("/self/software-agent/run", opts, {
         method: "POST",
         body: JSON.stringify(body),
@@ -217,6 +361,26 @@ program
     });
     console.log(JSON.stringify(data, null, 2));
 });
+program
+    .command("software-agent-tasks")
+    .description("List recent owner-only software-agent task ledger records")
+    .argument("[taskId]", "Task id to inspect")
+    .option("-p, --port <port>", "Local akemon serve port", "3000")
+    .option("-l, --limit <n>", "Maximum recent tasks to list", "20")
+    .option("--json", "Print raw JSON")
+    .action(async (taskId, opts) => {
+    const path = taskId
+        ? `/self/software-agent/tasks/${encodeURIComponent(taskId)}`
+        : `/self/software-agent/tasks?limit=${clampPositiveInt(opts.limit, 20, 100)}`;
+    const data = await callLocalOwnerEndpoint(path, opts, {
+        method: "GET",
+    });
+    if (opts.json || taskId) {
+        console.log(JSON.stringify(taskId ? data.task : data, null, 2));
+        return;
+    }
+    printSoftwareAgentTaskList(Array.isArray(data.tasks) ? data.tasks : []);
+});
 program
     .command("software-agent-reset")
     .description("Reset the owner-only local software-agent peripheral session")
@@ -227,6 +391,46 @@ program
     });
     console.log(JSON.stringify(data, null, 2));
 });
+program
+    .command("privacy-filter")
+    .description("Sanitize text with built-in redaction and optional OpenAI Privacy Filter")
+    .argument("<text...>", "Text to sanitize")
+    .option("--mode <mode>", "Mode: fast, pii, or strict", "fast")
+    .option("--backend <backend>", "Backend: fast or opf")
+    .option("--command <command>", "OPF command (default: opf)")
+    .option("--device <device>", "OPF device, e.g. cpu or cuda")
+    .option("--checkpoint <path>", "OPF checkpoint directory")
+    .option("--timeout-ms <ms>", "OPF timeout in milliseconds")
+    .option("--max-input-chars <n>", "Maximum text length to pass to OPF")
+    .option("--json", "Print result metadata as JSON")
+    .action(async (textParts, opts) => {
+    try {
+        const result = await sanitizeText(textParts.join(" "), {
+            mode: parsePrivacyFilterMode(opts.mode),
+            backend: parsePrivacyFilterBackend(opts.backend),
+            command: opts.command,
+            device: opts.device,
+            checkpoint: opts.checkpoint,
+            timeoutMs: parsePositiveIntCliOption(opts.timeoutMs, "--timeout-ms"),
+            maxInputChars: parsePositiveIntCliOption(opts.maxInputChars, "--max-input-chars"),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(result.text);
+        for (const warning of result.warnings) {
+            console.error(`[privacy-filter] ${warning}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof PrivacyFilterUnavailableError || error instanceof TypeError) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+});
 program
     .command("dashboard")
     .description("Open your agent dashboard in the browser")

package/dist/engine-peripheral.js

@@ -17,7 +17,7 @@ import { callAgent, sendTaskEnd, sendTaskStart, sendTaskStream } from "./relay-c
 import { SIG, sig } from "./types.js";
 import { updateMetrics, pushExecMs } from "./metrics.js";
 import { sendFailureEvent } from "./relay-client.js";
-import { resolveEngineConfig, } from "./engine-routing.js";
+import { resolveEngineRoute, } from "./engine-routing.js";
 export const LLM_ENGINES = new Set(["claude", "codex", "opencode", "gemini", "raw"]);
 const defaultTaskRelay = {
     sendTaskStart,
@@ -100,11 +100,12 @@ export class EnginePeripheral {
     // ---------------------------------------------------------------------------
     // Unified engine runner
     // ---------------------------------------------------------------------------
-    async runEngine(task, allowAll, extraAllowedTools, signal, origin, routing, taskId) {
-        const entry = resolveEngineConfig(routing, origin);
+    async runEngine(task, allowAll, extraAllowedTools, signal, origin, routing, taskId, routeRequest) {
+        const resolution = resolveEngineRoute(routing, { origin, ...routeRequest });
+        const entry = resolution.entry;
         const cfg = entry ? applyRoutingEntry(this.config, entry) : this.config;
         if (origin && entry) {
-            console.log(`[engine] using ${cfg.engine}${cfg.model ? `/${cfg.model}` : ""} (origin=${origin})`);
+            console.log(`[engine] using ${cfg.engine}${cfg.model ? `/${cfg.model}` : ""} (origin=${origin}, source=${resolution.source})`);
         }
         const t0 = Date.now();
         try {

package/dist/engine-routing.js

@@ -6,6 +6,15 @@
  *   deriveChildOrigin    — returns the origin a child/sub-task should carry
  *   downgradeForRetry    — downgrades any origin to "retry" when a task retries
  */
+export class EngineRegistry {
+    routing;
+    constructor(routing) {
+        this.routing = routing;
+    }
+    resolve(request = {}) {
+        return resolveEngineRoute(this.routing, request);
+    }
+}
 /**
  * Resolve which engine routing entry to use for a given origin.
  *
@@ -27,6 +36,34 @@ export function resolveEngineConfig(routing, origin) {
     }
     return routing.default ?? null;
 }
+export function resolveEngineRoute(routing, request = {}) {
+    if (!routing) {
+        return { entry: null, source: "none", reason: "no routing configured" };
+    }
+    const route = selectRoute(routing.routes, request);
+    if (route) {
+        return {
+            entry: stripRouteMetadata(route),
+            source: "route",
+            reason: "matched registry route",
+        };
+    }
+    if (request.origin && routing[request.origin]) {
+        return {
+            entry: routing[request.origin],
+            source: "origin",
+            reason: `matched legacy origin route ${request.origin}`,
+        };
+    }
+    if (routing.default) {
+        return {
+            entry: routing.default,
+            source: "default",
+            reason: "matched legacy default route",
+        };
+    }
+    return { entry: null, source: "none", reason: "no matching route" };
+}
 /**
  * Derive the origin that a child task should carry.
  *
@@ -50,3 +87,65 @@ export function deriveChildOrigin(_parentOrigin) {
 export function downgradeForRetry(_origin) {
     return "retry";
 }
+function selectRoute(routes, request) {
+    if (!routes?.length)
+        return null;
+    let best = null;
+    for (let index = 0; index < routes.length; index++) {
+        const route = routes[index];
+        if (!routeMatches(route, request))
+            continue;
+        const score = scoreRoute(route, request);
+        if (!best || score > best.score || (score === best.score && index < best.index)) {
+            best = { route, score, index };
+        }
+    }
+    return best?.route ?? null;
+}
+function routeMatches(route, request) {
+    if (request.origin && route.origins?.length && !route.origins.includes(request.origin))
+        return false;
+    if (!hasRequiredCapabilities(route.capabilities, request.requiredCapabilities))
+        return false;
+    if (request.privacy && route.privacy && route.privacy !== request.privacy)
+        return false;
+    if (request.maxCost && route.cost && tierRank(route.cost) > tierRank(request.maxCost))
+        return false;
+    if (request.maxLatency && route.latency && tierRank(route.latency) > tierRank(request.maxLatency))
+        return false;
+    return true;
+}
+function hasRequiredCapabilities(available, required) {
+    if (!required?.length)
+        return true;
+    if (!available?.length)
+        return false;
+    return required.every((capability) => available.includes(capability));
+}
+function scoreRoute(route, request) {
+    let score = route.priority ?? 0;
+    if (request.origin && route.origins?.includes(request.origin))
+        score += 100;
+    if (request.origin && !route.origins?.length)
+        score += 10;
+    if (request.requiredCapabilities?.length)
+        score += (route.capabilities?.length || 0) * 2;
+    if (request.privacy && route.privacy === request.privacy)
+        score += 20;
+    if (route.cost)
+        score += 6 - tierRank(route.cost);
+    if (route.latency)
+        score += 6 - tierRank(route.latency);
+    return score;
+}
+function stripRouteMetadata(route) {
+    const { origins: _origins, priority: _priority, ...entry } = route;
+    return entry;
+}
+function tierRank(tier) {
+    switch (tier) {
+        case "low": return 1;
+        case "medium": return 2;
+        case "high": return 3;
+    }
+}

package/dist/event-bus.js

@@ -4,7 +4,9 @@
  * SimpleEventBus: in-memory fire-and-forget. Async handlers don't block emitter.
  * PersistentEventBus: wraps SimpleEventBus + append-only jsonl log for crash recovery.
  */
-import { appendFileSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { redactSecrets } from "./redaction.js";
 export class SimpleEventBus {
     handlers = new Map();
     on(event, handler) {
@@ -66,19 +68,23 @@ export class SimpleEventBus {
         this.handlers.clear();
     }
 }
-// ---------------------------------------------------------------------------
-// FileEventLog — append-only jsonl file for event persistence
-// ---------------------------------------------------------------------------
+const DEFAULT_EVENT_LOG_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_EVENT_LOG_MAX_FILES = 5;
 export class FileEventLog {
     path;
-    constructor(path) {
+    maxBytes;
+    maxFiles;
+    constructor(path, options = {}) {
         this.path = path;
+        this.maxBytes = normalizePositiveInt(options.maxBytes, DEFAULT_EVENT_LOG_MAX_BYTES);
+        this.maxFiles = normalizePositiveInt(options.maxFiles, DEFAULT_EVENT_LOG_MAX_FILES);
         if (!existsSync(path))
             writeFileSync(path, "");
     }
     append(event, signal) {
         try {
-            const line = JSON.stringify({ e: event, s: signal }) + "\n";
+            const line = JSON.stringify(redactSecrets({ e: event, s: signal })) + "\n";
+            this.rotateIfNeeded(Buffer.byteLength(line, "utf8"));
             appendFileSync(this.path, line);
         }
         catch {
@@ -86,24 +92,64 @@ export class FileEventLog {
         }
     }
     async replay(handler) {
-        if (!existsSync(this.path))
-            return;
-        const content = readFileSync(this.path, "utf-8");
-        for (const line of content.split("\n")) {
-            if (!line.trim())
+        for (const file of this.replayPaths()) {
+            if (!existsSync(file))
                 continue;
-            try {
-                const { e, s } = JSON.parse(line);
-                handler(e, s);
-            }
-            catch {
-                // Skip corrupted lines
+            const content = readFileSync(file, "utf-8");
+            for (const line of content.split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const { e, s } = JSON.parse(line);
+                    handler(e, s);
+                }
+                catch {
+                    // Skip corrupted lines
+                }
             }
         }
     }
     close() {
         // No-op for sync file writes
     }
+    rotateIfNeeded(incomingBytes) {
+        if (this.maxBytes <= 0)
+            return;
+        if (!existsSync(this.path)) {
+            writeFileSync(this.path, "");
+            return;
+        }
+        const currentBytes = statSync(this.path).size;
+        if (currentBytes <= 0 || currentBytes + incomingBytes <= this.maxBytes)
+            return;
+        const oldest = this.rotatedPath(this.maxFiles);
+        if (existsSync(oldest))
+            unlinkSync(oldest);
+        for (let index = this.maxFiles - 1; index >= 1; index--) {
+            const from = this.rotatedPath(index);
+            if (existsSync(from))
+                renameSync(from, this.rotatedPath(index + 1));
+        }
+        renameSync(this.path, this.rotatedPath(1));
+        writeFileSync(this.path, "");
+    }
+    replayPaths() {
+        const paths = [];
+        for (let index = this.maxFiles; index >= 1; index--) {
+            paths.push(this.rotatedPath(index));
+        }
+        paths.push(this.path);
+        return paths;
+    }
+    rotatedPath(index) {
+        const dir = dirname(this.path);
+        const ext = extname(this.path);
+        const base = basename(this.path, ext);
+        return join(dir, `${base}.${index}${ext}`);
+    }
+}
+function normalizePositiveInt(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
 }
 // ---------------------------------------------------------------------------
 // PersistentEventBus — SimpleEventBus + append-only log