aiden-runtime 4.0.1 → 4.1.0

package/dist/core/v4/firstRun/providerDetection.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/firstRun/providerDetection.ts — Aiden v4.0.2 (Phase 30.2)
+ *
+ * Fast (< 100 ms) check at boot: does the user have ANY working
+ * provider configured? Drives the "auto-launch setup wizard if not"
+ * behaviour in cli/v4/aidenCLI.ts and the "model not configured"
+ * fallback in the boot card.
+ *
+ * Three signals are inspected, all local — no real API calls:
+ *
+ *   1. Env vars      — process.env keys matching any of the wizard's
+ *                      `PROVIDERS[].envVar` entries. (Wizard-managed
+ *                      `.env` is loaded into process.env upstream by
+ *                      `loadAidenEnvFile`, so this catches both shell
+ *                      env and Aiden's persisted .env.)
+ *
+ *   2. OAuth tokens  — `<paths.root>/auth/<provider>.json`. We treat
+ *                      the file's presence as "credentials available"
+ *                      — actual decrypt + expiry happens later in
+ *                      `runtimeResolver` and is reported via plugin
+ *                      boot-card status. Avoids paying scrypt + AES
+ *                      cost on every boot just to gate the wizard.
+ *
+ *   3. Ollama        — TCP probe of `http://localhost:11434/api/tags`
+ *                      with a HARD 80 ms abort. Non-fatal on timeout
+ *                      so a slow loopback doesn't slow boot.
+ *
+ * Returns a `ProviderDetection` snapshot the caller can consult to
+ * decide whether to launch the wizard. The shape is intentionally
+ * descriptive (lists, not just a boolean) so smoke tests and
+ * `aiden doctor` can render the why.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAvailableProviders = detectAvailableProviders;
+exports.summarizeDetection = summarizeDetection;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const setupWizard_1 = require("../../../cli/v4/setupWizard");
+/**
+ * Walk `PROVIDERS` and return env-var names whose value is set + non-empty.
+ * Includes the multi-slot Groq fallback vars so a user with `GROQ_API_KEY_2`
+ * but no primary still counts as configured.
+ */
+function detectEnvVars(env) {
+    const seen = new Set();
+    const out = [];
+    const consider = (name) => {
+        if (!name)
+            return;
+        if (seen.has(name))
+            return;
+        const val = env[name];
+        if (typeof val === 'string' && val.trim().length > 0) {
+            seen.add(name);
+            out.push(name);
+        }
+    };
+    for (const p of setupWizard_1.PROVIDERS)
+        consider(p.envVar);
+    // Multi-slot Groq fallbacks live in core/v4/providerFallback.ts. Keep
+    // this list local so detection has zero deep imports off the boot
+    // path; the fallback module is heavy.
+    for (const extra of [
+        'GROQ_API_KEY_2',
+        'GROQ_API_KEY_3',
+        'GROQ_API_KEY_4',
+        'TOGETHER_API_KEY',
+    ]) {
+        consider(extra);
+    }
+    return out;
+}
+/**
+ * Read `<paths.root>/auth/` and return provider ids whose `.json`
+ * file exists. ENOENT on the directory is treated as "no tokens".
+ */
+async function detectOAuthTokens(paths) {
+    const dir = node_path_1.default.join(paths.root, 'auth');
+    let entries;
+    try {
+        entries = await node_fs_1.promises.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.endsWith('.json'))
+            continue;
+        const id = e.replace(/\.json$/, '');
+        // tokenStore writes one JSON per provider id; the file itself is
+        // always non-empty when it exists. Skip the size check — the
+        // resolver will surface a corrupt file with a clear error.
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Quick local probe of an Ollama daemon. Hard-aborts at `timeoutMs`
+ * so a slow loopback (e.g. WSL2 mirror mode warming up) never delays
+ * boot past the budget.
+ */
+async function probeOllamaQuick(opts) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs);
+    try {
+        const res = await opts.fetchImpl('http://localhost:11434/api/tags', { signal: ctrl.signal });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Cheap regex parse of `model.provider:` / `model.modelId:` AND the
+ * `providers:` section from config.yaml. Avoids pulling in js-yaml on
+ * the boot hot-path. Tolerates quoted values and inline comments.
+ * Returns nulls / empty list when the file is missing.
+ *
+ * The `providers:` walker mirrors `cli/v4/setupWizard.isFreshInstall`
+ * so a config.yaml that only carries inline `providers.foo.apiKey`
+ * (no env var) still counts as "the user has configured something" —
+ * the moat-boot test suite relies on this fixture shape.
+ */
+async function readConfigProviders(configYaml) {
+    let text;
+    try {
+        text = await node_fs_1.promises.readFile(configYaml, 'utf8');
+    }
+    catch {
+        return { provider: null, model: null, configuredProviders: [] };
+    }
+    const lines = text.split(/\r?\n/);
+    let inModel = false;
+    let inProviders = false;
+    let provider = null;
+    let model = null;
+    // Two-line lookahead would let us match `apiKey: ...` under each
+    // provider id; instead we keep the most recently seen provider id
+    // and stamp it on `configuredProviders` when its child field is
+    // populated. Idempotent within a single file.
+    let currentProviderId = null;
+    const seenProviders = [];
+    for (const raw of lines) {
+        const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+        if (/^model\s*:\s*$/.test(line)) {
+            inModel = true;
+            inProviders = false;
+            currentProviderId = null;
+            continue;
+        }
+        if (/^providers\s*:\s*$/.test(line)) {
+            inProviders = true;
+            inModel = false;
+            currentProviderId = null;
+            continue;
+        }
+        // Top-level non-indented key ends both blocks.
+        if (/^\S/.test(line) && line.length > 0) {
+            inModel = false;
+            inProviders = false;
+            currentProviderId = null;
+            continue;
+        }
+        if (inModel) {
+            const provM = line.match(/^\s+provider\s*:\s*['"]?([^'"\s]+)['"]?\s*$/);
+            if (provM)
+                provider = provM[1];
+            const modM = line.match(/^\s+modelId\s*:\s*['"]?([^'"\s]+)['"]?\s*$/);
+            if (modM)
+                model = modM[1];
+            continue;
+        }
+        if (inProviders) {
+            // 2-space indented `<id>:` opens a provider entry.
+            const idM = line.match(/^  ([A-Za-z0-9_.-]+)\s*:\s*$/);
+            if (idM) {
+                currentProviderId = idM[1];
+                continue;
+            }
+            // 4-space indented `apiKey:` / `baseUrl:` flags it as configured.
+            if (currentProviderId &&
+                /^    (apiKey|baseUrl|auth)\s*:\s*\S/.test(line)) {
+                if (!seenProviders.includes(currentProviderId)) {
+                    seenProviders.push(currentProviderId);
+                }
+            }
+        }
+    }
+    return { provider, model, configuredProviders: seenProviders };
+}
+/**
+ * Map a config provider id to the env-var name(s) and/or OAuth provider
+ * id that would represent valid credentials for it. Drives the
+ * `configuredProviderHasCredentials` flag.
+ */
+function configProviderCredentialKeys(providerId) {
+    const entry = setupWizard_1.PROVIDERS.find((p) => p.id === providerId);
+    const envVars = [];
+    const oauthIds = [];
+    if (entry?.envVar)
+        envVars.push(entry.envVar);
+    // Pro/oauth providers store tokens under their provider id.
+    if (entry?.kind === 'pro' || entry?.kind === 'oauth') {
+        oauthIds.push(providerId);
+    }
+    // Ollama needs no credentials; mirror the env-var-less local-key path.
+    if (entry?.kind === 'local') {
+        envVars.push('__OLLAMA_REACHABLE__'); // sentinel handled by caller
+    }
+    return { envVars, oauthIds };
+}
+async function detectAvailableProviders(opts) {
+    const env = opts.env ?? process.env;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.ollamaTimeoutMs ?? 80;
+    // Run the four independent probes in parallel — Ollama is the only
+    // one that can take real wall time, but capping it at 80 ms keeps
+    // total detection cost under the 100 ms budget on every realistic host.
+    const [envVars, oauthTokens, ollamaReachable, cfg] = await Promise.all([
+        Promise.resolve(detectEnvVars(env)),
+        detectOAuthTokens(opts.paths),
+        opts.skipOllamaProbe
+            ? Promise.resolve(false)
+            : probeOllamaQuick({ fetchImpl, timeoutMs }),
+        readConfigProviders(opts.paths.configYaml),
+    ]);
+    const hasAnyProvider = envVars.length > 0 ||
+        oauthTokens.length > 0 ||
+        ollamaReachable ||
+        cfg.configuredProviders.length > 0;
+    let configuredProviderHasCredentials = false;
+    if (cfg.provider) {
+        const want = configProviderCredentialKeys(cfg.provider);
+        const envHit = want.envVars.some((v) => v === '__OLLAMA_REACHABLE__' ? ollamaReachable : envVars.includes(v));
+        const oauthHit = want.oauthIds.some((id) => oauthTokens.includes(id));
+        // Inline `providers.<id>.apiKey` in config.yaml is also a valid
+        // credential source — it's what the moat-boot fixtures rely on
+        // and what users get when they hand-edit config.yaml.
+        const inlineHit = cfg.configuredProviders.includes(cfg.provider);
+        configuredProviderHasCredentials = envHit || oauthHit || inlineHit;
+    }
+    return {
+        hasAnyProvider,
+        envVars,
+        oauthTokens,
+        ollamaReachable,
+        configProvider: cfg.provider,
+        configModel: cfg.model,
+        configuredProviders: cfg.configuredProviders,
+        configuredProviderHasCredentials,
+    };
+}
+/**
+ * Format a single-line summary suitable for the boot UX preamble.
+ * Public so the wizard auto-trigger path can mirror it and so smoke
+ * tests can assert on stable text.
+ */
+function summarizeDetection(d) {
+    if (d.hasAnyProvider) {
+        const parts = [];
+        if (d.envVars.length > 0)
+            parts.push(`env: ${d.envVars.length}`);
+        if (d.oauthTokens.length > 0)
+            parts.push(`oauth: ${d.oauthTokens.length}`);
+        if (d.ollamaReachable)
+            parts.push('ollama');
+        if (d.configuredProviders.length > 0) {
+            parts.push(`config: ${d.configuredProviders.length}`);
+        }
+        return `Providers detected — ${parts.join(', ')}.`;
+    }
+    return 'No AI provider configured yet.';
+}

package/dist/core/v4/logger/factory.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/factory.ts — Phase v4.1-1.3a
+ *
+ * Build a root `Logger` for the running process based on which mode
+ * Aiden is in. Each mode has different invariants:
+ *
+ *   - cli-interactive  — REPL is sacred. Zero stdout sinks. Errors go
+ *                        to stderr (visible to the user without
+ *                        touching the chat prompt). Everything to file.
+ *   - cli-headless     — `aiden setup`, `aiden doctor`, scripts. No
+ *                        REPL to protect. Warnings/errors go to stderr.
+ *                        Everything to file. Stdout stays free for the
+ *                        command's own output (so users can pipe).
+ *   - serve            — daemon. Logs go to stdout as NDJSON for systemd
+ *                        / docker / log aggregators. File mirror keeps
+ *                        a local trace.
+ *   - test             — vitest etc. NullSink only. Pass `withMemory:
+ *                        true` to swap in a MemorySink for assertions.
+ *
+ * Modules NEVER pick their own sinks — they receive a Logger and call
+ * `.info()` etc. The factory is the only place mode-routing decisions
+ * live.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBootLogger = createBootLogger;
+exports.noopLogger = noopLogger;
+exports.markReplActive = markReplActive;
+exports.markReplInactive = markReplInactive;
+exports.isReplActive = isReplActive;
+const logger_1 = require("./logger");
+const fileSink_1 = require("./sinks/fileSink");
+const stdSink_1 = require("./sinks/stdSink");
+const nullSink_1 = require("./sinks/nullSink");
+function createBootLogger(opts) {
+    switch (opts.mode) {
+        case 'cli-interactive': {
+            // REPL invariant: zero stdout writes. Stderr is allowed for
+            // warn/error so a real failure isn't completely silent.
+            const sinks = [];
+            if (opts.logsDir)
+                sinks.push(new fileSink_1.FileSink({ dir: opts.logsDir, name: 'aiden' }));
+            sinks.push(new stdSink_1.StderrSink({ minLevel: 'warn' }));
+            return { logger: new logger_1.CoreLogger({ sinks }) };
+        }
+        case 'cli-headless': {
+            const sinks = [];
+            if (opts.logsDir)
+                sinks.push(new fileSink_1.FileSink({ dir: opts.logsDir, name: 'aiden' }));
+            sinks.push(new stdSink_1.StderrSink({ minLevel: 'warn' }));
+            return { logger: new logger_1.CoreLogger({ sinks }) };
+        }
+        case 'serve': {
+            // Daemon — stdout NDJSON for log aggregators, mirror to file for
+            // local-on-disk debugging.
+            const sinks = [new stdSink_1.StdoutJsonSink()];
+            if (opts.logsDir)
+                sinks.push(new fileSink_1.FileSink({ dir: opts.logsDir, name: 'aiden' }));
+            return { logger: new logger_1.CoreLogger({ sinks }) };
+        }
+        case 'test': {
+            if (opts.withMemory) {
+                const memory = new nullSink_1.MemorySink();
+                return { logger: new logger_1.CoreLogger({ sinks: [memory] }), memory };
+            }
+            return { logger: new logger_1.CoreLogger({ sinks: [new nullSink_1.NullSink()] }) };
+        }
+        case 'mcp-stdio': {
+            // Phase v4.1-mcp invariant: stdout carries the JSON-RPC protocol
+            // frames — any byte written to stdout outside the MCP transport
+            // corrupts the wire. So this mode wires ZERO stdout sinks. Errors
+            // and warnings go to stderr (visible to the spawning client's log
+            // stream); everything else lands in the file sink for postmortems.
+            const sinks = [];
+            if (opts.logsDir)
+                sinks.push(new fileSink_1.FileSink({ dir: opts.logsDir, name: 'aiden-mcp' }));
+            sinks.push(new stdSink_1.StderrSink({ minLevel: 'warn' }));
+            return { logger: new logger_1.CoreLogger({ sinks }) };
+        }
+    }
+}
+/**
+ * No-op singleton — what `attachLogger()` setters fall back to when no
+ * caller has wired in a real one yet. Avoids null-checks at every emit
+ * site. Lazy-built so tests that import this module don't allocate
+ * sinks they'll never touch.
+ */
+let _noop = null;
+function noopLogger() {
+    if (!_noop)
+        _noop = new logger_1.CoreLogger({ sinks: [new nullSink_1.NullSink()] });
+    return _noop;
+}
+/**
+ * Phase v4.1-1.3a — process-wide flag tripped once the chat prompt is
+ * up. The repl-sacred invariant in `cli-interactive` mode comes from
+ * the factory not wiring any stdout sink, but a defense-in-depth layer:
+ * if any future code path manages to grab stdout directly, this flag
+ * lets us assert in tests + audit.
+ */
+let _replActive = false;
+function markReplActive() { _replActive = true; }
+function markReplInactive() { _replActive = false; }
+function isReplActive() { return _replActive; }

package/dist/core/v4/logger/index.js

@@ -0,0 +1,22 @@
+"use strict";
+// core/v4/logger/index.ts — Phase v4.1-1.3a barrel export.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiSink = exports.MemorySink = exports.NullSink = exports.StdoutJsonSink = exports.StderrSink = exports.FileSink = exports.isReplActive = exports.markReplInactive = exports.markReplActive = exports.noopLogger = exports.createBootLogger = exports.CoreLogger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "CoreLogger", { enumerable: true, get: function () { return logger_1.CoreLogger; } });
+var factory_1 = require("./factory");
+Object.defineProperty(exports, "createBootLogger", { enumerable: true, get: function () { return factory_1.createBootLogger; } });
+Object.defineProperty(exports, "noopLogger", { enumerable: true, get: function () { return factory_1.noopLogger; } });
+Object.defineProperty(exports, "markReplActive", { enumerable: true, get: function () { return factory_1.markReplActive; } });
+Object.defineProperty(exports, "markReplInactive", { enumerable: true, get: function () { return factory_1.markReplInactive; } });
+Object.defineProperty(exports, "isReplActive", { enumerable: true, get: function () { return factory_1.isReplActive; } });
+var fileSink_1 = require("./sinks/fileSink");
+Object.defineProperty(exports, "FileSink", { enumerable: true, get: function () { return fileSink_1.FileSink; } });
+var stdSink_1 = require("./sinks/stdSink");
+Object.defineProperty(exports, "StderrSink", { enumerable: true, get: function () { return stdSink_1.StderrSink; } });
+Object.defineProperty(exports, "StdoutJsonSink", { enumerable: true, get: function () { return stdSink_1.StdoutJsonSink; } });
+var nullSink_1 = require("./sinks/nullSink");
+Object.defineProperty(exports, "NullSink", { enumerable: true, get: function () { return nullSink_1.NullSink; } });
+Object.defineProperty(exports, "MemorySink", { enumerable: true, get: function () { return nullSink_1.MemorySink; } });
+var multiSink_1 = require("./sinks/multiSink");
+Object.defineProperty(exports, "MultiSink", { enumerable: true, get: function () { return multiSink_1.MultiSink; } });

package/dist/core/v4/logger/logger.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/logger.ts — Phase v4.1-1.3a
+ *
+ * The Logger contract. Every module that emits diagnostics goes through
+ * this — never `console.*` directly. The CLI's REPL is sacred: in
+ * `cli-interactive` mode the factory wires zero stdout sinks, so a
+ * misbehaving module CANNOT corrupt the chat prompt.
+ *
+ * Three pieces:
+ *   - `Logger`       — what consumers call (debug / info / warn / error
+ *                      + child(scope) for nested namespaces).
+ *   - `LoggerSink`   — where lines actually go (file, stderr, null, …).
+ *   - `Logger` impl  — fans every line out to all attached sinks.
+ *
+ * Sinks are the routing surface; the factory in `./factory.ts` picks
+ * the right combination per AidenMode. Adding a new module never
+ * touches sink logic — modules just call `logger.info('...')` and
+ * the factory decides where it goes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoreLogger = exports.LOG_LEVEL_ORDER = void 0;
+/** Stable numeric ordering for level filtering. */
+exports.LOG_LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/**
+ * Default `Logger` implementation. Holds a list of sinks and the
+ * current scope; child loggers share the same sink list (so updating
+ * the level / detaching at the root affects everything).
+ */
+class CoreLogger {
+    /**
+     * Construct a root logger. Use `child(segment)` for sub-loggers.
+     * `sinks` may be empty — useful for tests; writes silently drop.
+     */
+    constructor(opts) {
+        this.scope = opts.scope ?? '';
+        this.sinks = opts.sinks;
+        this.level = opts.level ?? 'debug';
+        this.sinksOwner = { sinks: this.sinks, level: this.level };
+    }
+    /** Internal — used by `child()` to share state with the root. */
+    static childOf(parent, segment) {
+        const c = Object.create(CoreLogger.prototype);
+        const nextScope = parent.scope ? `${parent.scope}.${segment}` : segment;
+        Object.assign(c, {
+            scope: nextScope,
+            sinks: parent.sinksOwner.sinks,
+            level: parent.sinksOwner.level,
+            sinksOwner: parent.sinksOwner,
+        });
+        return c;
+    }
+    child(segment) {
+        return CoreLogger.childOf(this, segment);
+    }
+    setLevel(level) {
+        this.sinksOwner.level = level;
+        this.level = level;
+    }
+    getLevel() {
+        return this.sinksOwner.level;
+    }
+    detachAll() {
+        this.sinksOwner.sinks.length = 0;
+    }
+    debug(msg, ctx) { this.write('debug', msg, ctx); }
+    info(msg, ctx) { this.write('info', msg, ctx); }
+    warn(msg, ctx) { this.write('warn', msg, ctx); }
+    error(msg, ctx) { this.write('error', msg, ctx); }
+    write(level, msg, ctx) {
+        if (exports.LOG_LEVEL_ORDER[level] < exports.LOG_LEVEL_ORDER[this.sinksOwner.level])
+            return;
+        const record = {
+            ts: new Date(),
+            level,
+            scope: this.scope,
+            msg,
+            ctx,
+        };
+        // Sinks must not throw — the helpers in ./sinks/* all wrap their
+        // I/O in try/catch. Be defensive anyway.
+        for (const s of this.sinksOwner.sinks) {
+            try {
+                s.write(record);
+            }
+            catch { /* logging must not break callers */ }
+        }
+    }
+}
+exports.CoreLogger = CoreLogger;

package/dist/core/v4/logger/sinks/fileSink.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/sinks/fileSink.ts — Phase v4.1-1.3a
+ *
+ * Append log records to a file under `<aidenRoot>/logs/<name>.log`.
+ *
+ * One file per stream. Synchronous append (`appendFileSync`) so a line
+ * is durable even if the process exits mid-emission — same trade-off
+ * `core/v4/aidenLogger.ts` makes; small writes (< 100 / s during boot,
+ * occasional after) keep the cost negligible.
+ *
+ * Coarse rotation: when the file passes `MAX_BYTES`, rename to
+ * `<name>.log.1` (overwriting any previous rotation). One rotation is
+ * enough for diagnostics — older history isn't useful for debugging
+ * the current session and we'd rather not stash megabytes.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSink = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/** Rotate at 5 MB — comfortable for a long debugging session, never huge. */
+const MAX_BYTES = 5 * 1024 * 1024;
+class FileSink {
+    constructor(opts) {
+        this.dirReady = false;
+        this.dir = opts.dir;
+        this.filePath = node_path_1.default.join(opts.dir, `${opts.name}.log`);
+    }
+    write(record) {
+        if (!this.ensureDir())
+            return;
+        this.maybeRotate();
+        const line = this.format(record);
+        try {
+            (0, node_fs_1.appendFileSync)(this.filePath, line, 'utf8');
+        }
+        catch { /* disk full / permission denied — drop */ }
+    }
+    /** Make `<dir>` once. Repeated calls are cheap (cache hit). */
+    ensureDir() {
+        if (this.dirReady)
+            return true;
+        try {
+            (0, node_fs_1.mkdirSync)(this.dir, { recursive: true });
+            this.dirReady = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * If the file is over MAX_BYTES, rename to `<name>.log.1` (overwriting
+     * the prior rotation if any). Best-effort — rotation failure isn't
+     * worth blocking the next write for.
+     */
+    maybeRotate() {
+        let size = 0;
+        try {
+            size = (0, node_fs_1.statSync)(this.filePath).size;
+        }
+        catch {
+            return;
+        }
+        if (size <= MAX_BYTES)
+            return;
+        try {
+            (0, node_fs_1.renameSync)(this.filePath, `${this.filePath}.1`);
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Pretty single-line format — easy to grep, easy to tail. Structured
+     * fields are appended JSON-style after the message. Sinks that want
+     * NDJSON live elsewhere (e.g. `serve` mode would use a future
+     * JsonStdoutSink).
+     *
+     *   2026-05-08T01:32:44.681Z [info] [channels.telegram] Connected as @bot
+     *   2026-05-08T01:32:50.001Z [warn] [channels.telegram] Polling 409 {"streak":1}
+     */
+    format(r) {
+        const scope = r.scope ? ` [${r.scope}]` : '';
+        const ctx = r.ctx && Object.keys(r.ctx).length > 0
+            ? ' ' + safeJson(r.ctx)
+            : '';
+        return `${r.ts.toISOString()} [${r.level}]${scope} ${r.msg}${ctx}\n`;
+    }
+}
+exports.FileSink = FileSink;
+/**
+ * Defensive JSON.stringify — never throws; circular refs collapse to a
+ * placeholder so a misbehaving caller can't kill the log line.
+ */
+function safeJson(obj) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return '"[unserializable ctx]"';
+    }
+}

package/dist/core/v4/logger/sinks/multiSink.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/sinks/multiSink.ts — Phase v4.1-1.3a
+ *
+ * `Logger` already fans out to every attached sink, so MultiSink is
+ * thin sugar for the cases where a sink itself wants to delegate to
+ * several others (e.g. wrap a stderr-warn-only filter and a file
+ * everything filter behind a single object the caller treats as one
+ * sink). In 3a it's used by tests; production logger compositions go
+ * through `factory.createBootLogger` which picks sinks per mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiSink = void 0;
+class MultiSink {
+    constructor(children) {
+        this.children = children;
+    }
+    write(r) {
+        for (const c of this.children) {
+            try {
+                c.write(r);
+            }
+            catch { /* one sink's failure must not poison the others */ }
+        }
+    }
+    async close() {
+        for (const c of this.children) {
+            if (typeof c.close === 'function') {
+                try {
+                    await c.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+}
+exports.MultiSink = MultiSink;