@openlife/cli 1.7.3

package/dist/orchestrator/RoleHandoff.js

@@ -0,0 +1,65 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleHandoff = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class RoleHandoff {
+    filePath;
+    constructor() {
+        this.filePath = path.join(process.cwd(), '.artifacts', 'role-handoffs.json');
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    }
+    create(input) {
+        const all = this.getAll();
+        all.push({ ...input, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+        fs.writeFileSync(this.filePath, JSON.stringify(all, null, 2), 'utf-8');
+    }
+    updateStatus(id, status) {
+        const all = this.getAll().map((item) => item.id === id ? { ...item, status, updatedAt: new Date().toISOString() } : item);
+        fs.writeFileSync(this.filePath, JSON.stringify(all, null, 2), 'utf-8');
+    }
+    getAll() {
+        if (!fs.existsSync(this.filePath))
+            return [];
+        try {
+            return JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.RoleHandoff = RoleHandoff;

package/dist/orchestrator/RuntimeHealthMonitor.js

@@ -0,0 +1,143 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeHealthMonitor = exports.RETRY_BUDGET_WINDOW_MS = exports.MAX_FAILURES = exports.MAX_DELAY_MS = exports.BASE_DELAY_MS = void 0;
+exports.exponentialBackoffDelayMs = exponentialBackoffDelayMs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const AtomicWriter_1 = require("./util/AtomicWriter");
+/**
+ * Exponential backoff parameters.
+ *
+ *   delay = min(BASE_DELAY_MS * 2^(failures-1), MAX_DELAY_MS)
+ *
+ * After MAX_FAILURES failures within RETRY_BUDGET_WINDOW_MS the executor
+ * is marked permanentlyDown until manual reset via markHealthy().
+ *
+ * Story 6.5 — OpenLife v1.2 Royal Stack.
+ */
+exports.BASE_DELAY_MS = 10_000; // 10s for first failure
+exports.MAX_DELAY_MS = 60 * 60 * 1000; // 1h cap
+exports.MAX_FAILURES = 10; // budget
+exports.RETRY_BUDGET_WINDOW_MS = 60 * 60 * 1000; // 1h window
+function exponentialBackoffDelayMs(failures) {
+    if (failures <= 0)
+        return exports.BASE_DELAY_MS;
+    const exponent = Math.min(failures - 1, 30); // clamp to avoid 2^N overflow
+    const delay = exports.BASE_DELAY_MS * Math.pow(2, exponent);
+    return Math.min(delay, exports.MAX_DELAY_MS);
+}
+class RuntimeHealthMonitor {
+    root;
+    filePath;
+    constructor(root = process.cwd()) {
+        this.root = root;
+        this.filePath = path.join(this.root, '.openlife', 'runtime-health.json');
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    }
+    read() {
+        if (!fs.existsSync(this.filePath))
+            return {};
+        try {
+            return JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    write(payload) {
+        (0, AtomicWriter_1.writeJsonAtomic)(this.filePath, payload);
+    }
+    get(executor) {
+        return this.read()[executor] || null;
+    }
+    isCoolingDown(executor) {
+        const state = this.get(executor);
+        if (!state)
+            return false;
+        if (state.permanentlyDown)
+            return true;
+        if (!state.until)
+            return false;
+        return new Date(state.until).getTime() > Date.now();
+    }
+    /**
+     * Record an executor failure. The cooldown is computed via exponential
+     * backoff unless `cooldownMinutes` is explicitly provided (backward-
+     * compatible — pre-v1.2 callers passed a fixed 10-minute window).
+     */
+    markFailure(executor, reason, cooldownMinutes) {
+        const current = this.read();
+        const existing = current[executor];
+        const now = Date.now();
+        // Reset the failure window if more than RETRY_BUDGET_WINDOW_MS elapsed
+        // since the window started — gives intermittent failures a clean slate.
+        let failures = (existing?.failures || 0) + 1;
+        let budgetWindowStartedAt = existing?.budgetWindowStartedAt;
+        if (!budgetWindowStartedAt || now - budgetWindowStartedAt > exports.RETRY_BUDGET_WINDOW_MS) {
+            budgetWindowStartedAt = now;
+            failures = 1;
+        }
+        const permanentlyDown = failures > exports.MAX_FAILURES;
+        const delayMs = cooldownMinutes !== undefined
+            ? cooldownMinutes * 60 * 1000
+            : exponentialBackoffDelayMs(failures);
+        const until = permanentlyDown ? undefined : new Date(now + delayMs).toISOString();
+        current[executor] = {
+            executor,
+            failures,
+            until,
+            reason,
+            updatedAt: new Date().toISOString(),
+            permanentlyDown,
+            budgetWindowStartedAt,
+        };
+        this.write(current);
+    }
+    markHealthy(executor) {
+        const current = this.read();
+        current[executor] = {
+            executor,
+            failures: 0,
+            updatedAt: new Date().toISOString(),
+            permanentlyDown: false,
+        };
+        this.write(current);
+    }
+    all() {
+        return this.read();
+    }
+}
+exports.RuntimeHealthMonitor = RuntimeHealthMonitor;

package/dist/orchestrator/RuntimePolicy.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimePolicy = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ExecutorHealth_1 = require("./ExecutorHealth");
+const RuntimeHealthMonitor_1 = require("./RuntimeHealthMonitor");
+class RuntimePolicy {
+    executorHealth;
+    runtimeHealth;
+    constructor() {
+        this.executorHealth = new ExecutorHealth_1.ExecutorHealth();
+        this.runtimeHealth = new RuntimeHealthMonitor_1.RuntimeHealthMonitor();
+    }
+    decide(intent, explicitExecutors = []) {
+        const base = explicitExecutors.length
+            ? explicitExecutors
+            : intent === 'RESEARCH_ANALYSIS'
+                ? ['gemini', 'claude', 'codex']
+                : ['codex', 'claude', 'gemini'];
+        const allowedRaw = (process.env.OPENLIFE_ALLOWED_LLM_EXECUTORS || '').trim().toLowerCase();
+        const allowed = new Set();
+        if (allowedRaw) {
+            for (const entry of allowedRaw.split(',').map(s => s.trim()).filter(Boolean)) {
+                if (entry === 'codex' || entry === 'gemini' || entry === 'claude' || entry === 'openclaude') {
+                    allowed.add(entry);
+                }
+            }
+        }
+        const allowFiltered = allowed.size > 0 ? base.filter(e => allowed.has(e)) : base;
+        const preferred = allowFiltered.filter((executor) => {
+            const health = this.executorHealth.get(executor);
+            if (this.runtimeHealth.isCoolingDown(executor))
+                return false;
+            if (!health)
+                return true;
+            return health.available !== false;
+        });
+        return {
+            preferred,
+            rationale: preferred.length
+                ? `Executores ordenados por policy + health atual${allowed.size > 0 ? ' + allowlist' : ''}.`
+                : 'Todos os executores da cadeia configurada estão indisponíveis no momento.'
+        };
+    }
+    recordResult(executor, ok, reason) {
+        this.executorHealth.set(executor, ok, reason);
+        if (ok) {
+            this.runtimeHealth.markHealthy(executor);
+            return;
+        }
+        const normalized = (reason || '').toLowerCase();
+        const shouldCooldown = /quota|429|capacity|rate limit|temporarily unavailable|overloaded|auth/i.test(normalized);
+        if (shouldCooldown) {
+            const cooldown = /auth/i.test(normalized) ? 30 : 10;
+            this.runtimeHealth.markFailure(executor, reason || 'runtime failure', cooldown);
+        }
+    }
+    status() {
+        return {
+            executors: this.executorHealth.getAll(),
+            cooldowns: this.runtimeHealth.all()
+        };
+    }
+    saveSnapshot() {
+        const snapshotPath = path.join(process.cwd(), '.openlife', 'runtime-policy-status.json');
+        fs.mkdirSync(path.dirname(snapshotPath), { recursive: true });
+        fs.writeFileSync(snapshotPath, JSON.stringify(this.status(), null, 2), 'utf-8');
+        return snapshotPath;
+    }
+}
+exports.RuntimePolicy = RuntimePolicy;

package/dist/orchestrator/RuntimeProbe.js

@@ -0,0 +1,97 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeProbe = void 0;
+const child_process = __importStar(require("child_process"));
+const util_1 = require("util");
+const ExecutorHealth_1 = require("./ExecutorHealth");
+const execFile = (0, util_1.promisify)(child_process.execFile);
+class RuntimeProbe {
+    executorHealth;
+    constructor() {
+        this.executorHealth = new ExecutorHealth_1.ExecutorHealth();
+    }
+    async probeAll() {
+        const executors = ['codex', 'gemini', 'claude', 'openclaude'];
+        const results = [];
+        for (const executor of executors) {
+            results.push(await this.probe(executor));
+        }
+        return results;
+    }
+    async probe(executor) {
+        try {
+            const command = this.commandFor(executor);
+            const { stdout, stderr } = await execFile(command[0], command.slice(1), { timeout: 15000, maxBuffer: 1024 * 1024 * 5 });
+            const detail = (stdout || stderr || 'ok').toString().trim().slice(0, 200) || 'ok';
+            this.executorHealth.set(executor, true, detail);
+            return {
+                executor,
+                available: true,
+                reason: detail,
+                category: 'ok',
+                updatedAt: new Date().toISOString(),
+                command
+            };
+        }
+        catch (error) {
+            const probeErr = error;
+            const reason = probeErr.stderr || probeErr.stdout || probeErr.message || 'probe failed';
+            this.executorHealth.set(executor, false, String(reason));
+            const state = this.executorHealth.get(executor);
+            return {
+                executor,
+                available: false,
+                reason: String(reason).slice(0, 300),
+                category: state.category,
+                updatedAt: new Date().toISOString(),
+                command: this.commandFor(executor)
+            };
+        }
+    }
+    commandFor(executor) {
+        switch (executor) {
+            case 'gemini':
+                return ['gemini', '--version'];
+            case 'claude':
+                return ['claude', '--version'];
+            case 'openclaude':
+                return ['openclaude', '--version'];
+            default:
+                return ['codex', '--version'];
+        }
+    }
+}
+exports.RuntimeProbe = RuntimeProbe;

package/dist/orchestrator/RuntimeRegistry.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeRegistry = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const AtomicWriter_1 = require("./util/AtomicWriter");
+class RuntimeRegistry {
+    filePath;
+    constructor(workspaceId = 'default') {
+        this.filePath = path.join(process.cwd(), '.artifacts', 'workspaces', workspaceId, 'runtime-registry.json');
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    }
+    probe() {
+        const now = new Date().toISOString();
+        const entries = [
+            { id: 'local-shell', kind: 'local', available: true, checkedAt: now },
+            { id: 'codex-cli', kind: 'cli', available: this.hasCmd('codex'), checkedAt: now },
+            { id: 'gemini-cli', kind: 'cli', available: this.hasCmd('gemini'), checkedAt: now },
+            { id: 'claude-cli', kind: 'cli', available: this.hasCmd('claude'), checkedAt: now }
+        ];
+        (0, AtomicWriter_1.writeJsonAtomic)(this.filePath, entries);
+        return entries;
+    }
+    list() {
+        if (!fs.existsSync(this.filePath))
+            return this.probe();
+        return JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+    }
+    hasCmd(cmd) {
+        try {
+            const { execSync } = require('child_process');
+            execSync(`command -v ${cmd}`, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.RuntimeRegistry = RuntimeRegistry;

package/dist/orchestrator/SandboxPolicy.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxPolicy = void 0;
+class SandboxPolicy {
+    evaluate(executor, riskLevel) {
+        if (riskLevel === 'high' && executor !== 'codex') {
+            return {
+                executor,
+                allowed: false,
+                mode: 'restricted',
+                rationale: 'Executores secundários não podem rodar missões de alto risco.'
+            };
+        }
+        return {
+            executor,
+            allowed: true,
+            mode: riskLevel === 'high' ? 'restricted' : 'baseline',
+            rationale: riskLevel === 'high' ? 'Missão de alto risco liberada apenas em modo restrito.' : 'Execução liberada no baseline atual.'
+        };
+    }
+}
+exports.SandboxPolicy = SandboxPolicy;

package/dist/orchestrator/SecurityDownloadGuard.js

@@ -0,0 +1,169 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityDownloadGuard = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const ToolsetGuard_1 = require("./toolset/ToolsetGuard");
+class SecurityDownloadGuard {
+    blockedPatterns = [
+        /(^|\/)\.git(\/|$)/i,
+        /(^|\/)node_modules(\/|$)/i,
+        /\.(exe|dll|bat|cmd|ps1|scr|com)$/i,
+        /(^|\/)__MACOSX(\/|$)/i,
+        /(^|\/)\.env/i,
+    ];
+    validateUrl(url) {
+        const trusted = [
+            'https://skills.sh/',
+            'https://clawhub.ai/',
+            'https://mcpmarket.com/',
+            'https://mcpservers.org/',
+            'https://github.com/'
+        ];
+        const ok = trusted.some(t => url.startsWith(t));
+        return ok
+            ? { ok: true, blocked: [], warnings: [] }
+            : { ok: false, blocked: [url], warnings: ['untrusted_source'] };
+    }
+    scanFileList(paths) {
+        const blocked = paths.filter(p => this.blockedPatterns.some(rx => rx.test(p)));
+        const warnings = [];
+        if (paths.some(p => p.endsWith('.md') === false))
+            warnings.push('non_markdown_content_detected');
+        return { ok: blocked.length === 0, blocked, warnings };
+    }
+    scanExtractedDir(rootDir) {
+        const all = [];
+        const walk = (dir) => {
+            for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = `${dir}/${e.name}`;
+                if (e.isDirectory())
+                    walk(full);
+                else
+                    all.push(full.replace(`${rootDir}/`, ''));
+            }
+        };
+        walk(rootDir);
+        return this.scanFileList(all);
+    }
+    /**
+     * Story 9.1 — fetch a URL into a quarantine directory and run the
+     * existing scan pipeline before letting the caller move into `.catalog/`.
+     *
+     * Returns DownloadAndScanResult. Never throws. Caller is responsible
+     * for moving `downloadedTo` into its final home after inspecting the
+     * result.
+     *
+     * v1.4 supports single-file fetch only (markdown, YAML, JSON). Archive
+     * unpacking (zip / tar) is deferred to v1.5 — for v1.4, sources serve
+     * one manifest per import and we just trust the response body.
+     */
+    async downloadAndScan(url, targetDirOpt, opts = {}) {
+        (0, ToolsetGuard_1.assertToolsetAllowed)('web', 'SecurityDownloadGuard.downloadAndScan');
+        const errors = [];
+        const warnings = [];
+        const urlCheck = this.validateUrl(url);
+        if (!urlCheck.ok) {
+            return { ok: false, errors: ['untrusted_url'], warnings: urlCheck.warnings };
+        }
+        const targetDir = targetDirOpt || fs.mkdtempSync(path.join(os.tmpdir(), 'openlife-dl-'));
+        fs.mkdirSync(targetDir, { recursive: true });
+        const timeoutMs = opts.timeoutMs ?? 15000;
+        const maxBytes = opts.maxBytes ?? 5 * 1024 * 1024; // 5 MB cap
+        let body;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const res = await fetch(url, { signal: controller.signal });
+            clearTimeout(timer);
+            if (!res.ok) {
+                errors.push(`fetch_status_${res.status}`);
+                return { ok: false, errors, warnings };
+            }
+            const contentLength = Number(res.headers.get('content-length') || '0');
+            if (contentLength > maxBytes) {
+                errors.push(`content_too_large:${contentLength}>max:${maxBytes}`);
+                return { ok: false, errors, warnings };
+            }
+            body = await res.arrayBuffer();
+            if (body.byteLength > maxBytes) {
+                errors.push(`body_too_large:${body.byteLength}`);
+                return { ok: false, errors, warnings };
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`fetch_exception:${msg}`);
+            return { ok: false, errors, warnings };
+        }
+        // Choose a filename from the URL path (last segment, with fallback).
+        let filename = path.basename(new URL(url).pathname) || 'download.bin';
+        // Reject filenames that match blocked patterns (e.g. .exe, .dll).
+        const fileScan = this.scanFileList([filename]);
+        if (!fileScan.ok) {
+            errors.push(`filename_blocked:${fileScan.blocked.join(',')}`);
+            return { ok: false, errors, warnings: [...warnings, ...fileScan.warnings] };
+        }
+        const outPath = path.join(targetDir, filename);
+        try {
+            fs.writeFileSync(outPath, Buffer.from(body));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`write_exception:${msg}`);
+            return { ok: false, errors, warnings };
+        }
+        // Re-scan the dir for defence in depth.
+        const dirScan = this.scanExtractedDir(targetDir);
+        if (!dirScan.ok) {
+            errors.push(`dir_scan_blocked:${dirScan.blocked.join(',')}`);
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch { /* ignore */ }
+            return { ok: false, errors, warnings: [...warnings, ...dirScan.warnings] };
+        }
+        return {
+            ok: true,
+            downloadedTo: outPath,
+            bytesWritten: body.byteLength,
+            errors,
+            warnings: [...warnings, ...urlCheck.warnings, ...dirScan.warnings],
+        };
+    }
+}
+exports.SecurityDownloadGuard = SecurityDownloadGuard;