context-mode 1.0.168 → 2.0.0-next.5

package/build/pi-extension.js

@@ -1,451 +0,0 @@
-/**
- * Pi coding agent extension for context-mode.
- *
- * Follows the OpenClaw adapter pattern: imports shared session modules,
- * registers Pi-specific hooks. NO copy-paste of session logic.
- * NO external npm dependencies beyond what Pi runtime provides.
- *
- * Entry point: `export default function(pi: ExtensionAPI) { ... }`
- *
- * Lifecycle: session_start, tool_call, tool_result, before_agent_start,
- * session_before_compact, session_compact, session_shutdown.
- */
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve, dirname } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { SessionDB } from "./session/db.js";
-import { extractEvents, extractUserEvents } from "./session/extract.js";
-import { buildResumeSnapshot } from "./session/snapshot.js";
-// ── Pi Tool Name Mapping ─────────────────────────────────
-// Pi uses lowercase; shared extractors expect PascalCase (Claude Code convention).
-const PI_TOOL_MAP = {
-    bash: "Bash",
-    read: "Read",
-    write: "Write",
-    edit: "Edit",
-    grep: "Grep",
-    find: "Glob",
-    ls: "Glob",
-};
-// ── Routing patterns ─────────────────────────────────────
-// Inline HTTP client patterns to block in bash — self-contained, no routing module needed.
-const BLOCKED_BASH_PATTERNS = [
-    /\bcurl\s/,
-    /\bwget\s/,
-    /\bfetch\s*\(/,
-    /\brequests\.get\s*\(/,
-    /\brequests\.post\s*\(/,
-    /\bhttp\.get\s*\(/,
-    /\bhttp\.request\s*\(/,
-    /\burllib\.request/,
-    /\bInvoke-WebRequest\b/,
-];
-// ── Module-level DB singleton ────────────────────────────
-let _db = null;
-let _sessionId = "";
-// Per-session gate: routing block injected at most once per session_id.
-const _routingInjected = new Set();
-// Cached routing-block string (built once per process from hooks/routing-block.mjs).
-let _routingBlock = null;
-async function getRoutingBlock(pluginRoot) {
-    if (_routingBlock !== null)
-        return _routingBlock;
-    try {
-        const routingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "routing-block.mjs")).href);
-        const namingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "core", "tool-naming.mjs")).href);
-        const t = namingMod.createToolNamer("pi");
-        _routingBlock = String(routingMod.createRoutingBlock(t));
-    }
-    catch {
-        _routingBlock = "";
-    }
-    return _routingBlock;
-}
-// Cached buildAutoInjection (500-token cap, prioritized).
-let _buildAutoInjection = undefined;
-async function getAutoInjection(pluginRoot) {
-    if (_buildAutoInjection !== undefined)
-        return _buildAutoInjection;
-    try {
-        const mod = await import(pathToFileURL(join(pluginRoot, "hooks", "auto-injection.mjs")).href);
-        _buildAutoInjection = mod.buildAutoInjection;
-    }
-    catch {
-        _buildAutoInjection = null;
-    }
-    return _buildAutoInjection ?? null;
-}
-// ── Helpers ──────────────────────────────────────────────
-function getSessionDir() {
-    const dir = join(homedir(), ".pi", "context-mode", "sessions");
-    mkdirSync(dir, { recursive: true });
-    return dir;
-}
-function getDBPath() {
-    return join(getSessionDir(), "context-mode.db");
-}
-function getOrCreateDB() {
-    if (!_db) {
-        _db = new SessionDB({ dbPath: getDBPath() });
-    }
-    return _db;
-}
-/** Derive a stable session ID from Pi's session file path (SHA256, 16 hex chars). */
-function deriveSessionId(ctx) {
-    try {
-        const sessionManager = ctx.sessionManager;
-        const sessionFile = sessionManager?.getSessionFile?.();
-        if (sessionFile && typeof sessionFile === "string") {
-            return createHash("sha256").update(sessionFile).digest("hex").slice(0, 16);
-        }
-    }
-    catch {
-        // best effort
-    }
-    return `pi-${Date.now()}`;
-}
-/** Build stats text for the /ctx-stats command. */
-function buildStatsText(db, sessionId) {
-    try {
-        const events = db.getEvents(sessionId);
-        const stats = db.getSessionStats(sessionId);
-        const lines = [
-            "## context-mode stats (Pi)",
-            "",
-            `- Session: \`${sessionId.slice(0, 8)}...\``,
-            `- Events captured: ${events.length}`,
-            `- Compactions: ${stats?.compact_count ?? 0}`,
-        ];
-        // Event breakdown by category
-        const byCategory = {};
-        for (const ev of events) {
-            const key = ev.category ?? "unknown";
-            byCategory[key] = (byCategory[key] ?? 0) + 1;
-        }
-        if (Object.keys(byCategory).length > 0) {
-            lines.push("- Event breakdown:");
-            for (const [category, count] of Object.entries(byCategory)) {
-                lines.push(`  - ${category}: ${count}`);
-            }
-        }
-        // Session age
-        if (stats?.started_at) {
-            const startedMs = new Date(stats.started_at).getTime();
-            const ageMinutes = Math.round((Date.now() - startedMs) / 60_000);
-            lines.push(`- Session age: ${ageMinutes}m`);
-        }
-        return lines.join("\n");
-    }
-    catch {
-        return "context-mode stats unavailable (session DB error)";
-    }
-}
-function resolveCommandContext(argsOrCtx, ctx) {
-    if (ctx !== undefined)
-        return ctx;
-    if (argsOrCtx && typeof argsOrCtx === "object")
-        return argsOrCtx;
-    return undefined;
-}
-function handleCommandText(text, ctx) {
-    if (ctx?.hasUI) {
-        ctx.ui.notify(text, "info");
-        return;
-    }
-    return { text };
-}
-// ── Extension entry point ────────────────────────────────
-/** Pi extension default export. Called once by Pi runtime with the extension API. */
-export default function piExtension(pi) {
-    const buildDir = dirname(fileURLToPath(import.meta.url));
-    const pluginRoot = resolve(buildDir, "..");
-    const projectDir = process.env.PI_PROJECT_DIR || process.cwd();
-    const db = getOrCreateDB();
-    // ── 1. session_start — Initialize session ──────────────
-    pi.on("session_start", (ctx) => {
-        try {
-            _sessionId = deriveSessionId(ctx ?? {});
-            db.ensureSession(_sessionId, projectDir);
-            db.cleanupOldSessions(7);
-        }
-        catch {
-            // best effort — never break session start
-            if (!_sessionId) {
-                _sessionId = `pi-${Date.now()}`;
-            }
-        }
-    });
-    // ── 2. tool_call — PreToolUse routing enforcement ──────
-    // Block bash commands that contain curl/wget/fetch/requests patterns.
-    pi.on("tool_call", (event) => {
-        try {
-            const toolName = String(event?.toolName ?? "").toLowerCase();
-            if (toolName !== "bash")
-                return;
-            const command = String(event?.input?.command ?? "");
-            if (!command)
-                return;
-            const isBlocked = BLOCKED_BASH_PATTERNS.some((p) => p.test(command));
-            if (isBlocked) {
-                return {
-                    block: true,
-                    reason: "Use context-mode MCP tools (execute, fetch_and_index) instead of inline HTTP clients. " +
-                        "Raw curl/wget/fetch output floods the context window.",
-                };
-            }
-        }
-        catch {
-            // Routing failure — allow passthrough
-        }
-    });
-    // ── 3. tool_result — PostToolUse event capture ─────────
-    pi.on("tool_result", (event) => {
-        try {
-            if (!_sessionId)
-                return;
-            const rawToolName = String(event?.toolName ?? event?.tool_name ?? "");
-            const mappedToolName = PI_TOOL_MAP[rawToolName.toLowerCase()] ?? rawToolName;
-            // Normalize result to string
-            const rawResult = event?.result ?? event?.output;
-            const resultStr = typeof rawResult === "string"
-                ? rawResult
-                : rawResult != null
-                    ? JSON.stringify(rawResult)
-                    : undefined;
-            // Detect errors
-            const hasError = Boolean(event?.error || event?.isError);
-            const hookInput = {
-                tool_name: mappedToolName,
-                tool_input: event?.params ?? event?.input ?? {},
-                tool_response: resultStr,
-                tool_output: hasError ? { isError: true } : undefined,
-            };
-            const events = extractEvents(hookInput);
-            if (events.length > 0) {
-                for (const ev of events) {
-                    db.insertEvent(_sessionId, ev, "PostToolUse");
-                }
-            }
-            else if (rawToolName) {
-                // Fallback: record unrecognized tool call as generic event
-                const data = JSON.stringify({
-                    tool: rawToolName,
-                    params: event?.params ?? event?.input,
-                });
-                db.insertEvent(_sessionId, {
-                    type: "tool_call",
-                    category: "pi",
-                    data,
-                    priority: 1,
-                    data_hash: createHash("sha256")
-                        .update(data)
-                        .digest("hex")
-                        .slice(0, 16),
-                }, "PostToolUse");
-            }
-        }
-        catch {
-            // Silent — session capture must never break the tool call
-        }
-    });
-    // ── 4. before_agent_start — Routing + active_memory + resume injection ─
-    pi.on("before_agent_start", async (event) => {
-        try {
-            if (!_sessionId)
-                return;
-            const prompt = String(event?.prompt ?? "");
-            // Extract user events from the prompt text
-            if (prompt) {
-                const userEvents = extractUserEvents(prompt);
-                for (const ev of userEvents) {
-                    db.insertEvent(_sessionId, ev, "UserPromptSubmit");
-                }
-            }
-            const existingPrompt = String(event?.systemPrompt ?? "");
-            const parts = [];
-            if (existingPrompt)
-                parts.push(existingPrompt);
-            // Pi-1: Inject routing block once per session (gated by _routingInjected).
-            // v1.0.107 — visible marker so Pi users can verify the routing block
-            // reached the model (Mickey-class verification path; mirrors OpenCode).
-            if (!_routingInjected.has(_sessionId)) {
-                const routingBlock = await getRoutingBlock(pluginRoot);
-                if (routingBlock) {
-                    const marker = `<!-- context-mode: routing block injected (sessionID=${String(_sessionId).slice(0, 8)}) -->`;
-                    parts.push(marker + "\n" + routingBlock);
-                    _routingInjected.add(_sessionId);
-                }
-            }
-            // Pi-3 + Pi-4: Always build active_memory (not just post-compact),
-            // capped at 500 tokens via buildAutoInjection. Falls back to inline
-            // budget loop if the helper is unavailable.
-            const activeEvents = db.getEvents(_sessionId, {
-                minPriority: 3,
-                limit: 50,
-            });
-            if (activeEvents.length > 0) {
-                const buildAuto = await getAutoInjection(pluginRoot);
-                let memoryContext = "";
-                if (buildAuto) {
-                    memoryContext = buildAuto(activeEvents.map((e) => ({
-                        category: String(e.category ?? ""),
-                        data: String(e.data ?? ""),
-                    })));
-                }
-                // Fallback (or if helper produced empty output): inline 500-token cap.
-                if (!memoryContext) {
-                    const memoryLines = ["<active_memory>"];
-                    let budget = 2000; // ~500 tokens at 4 chars/token
-                    for (const ev of activeEvents) {
-                        const line = `  <event type="${ev.type}" category="${ev.category}">${ev.data}</event>`;
-                        if (line.length > budget)
-                            break;
-                        memoryLines.push(line);
-                        budget -= line.length;
-                    }
-                    memoryLines.push("</active_memory>");
-                    if (memoryLines.length > 2)
-                        memoryContext = memoryLines.join("\n");
-                }
-                if (memoryContext)
-                    parts.push(memoryContext);
-            }
-            // Resume snapshot (only when present and unconsumed).
-            const resume = db.getResume(_sessionId);
-            if (resume && !resume.consumed && resume.snapshot) {
-                parts.push(resume.snapshot);
-                db.markResumeConsumed(_sessionId);
-            }
-            // Return modified systemPrompt only if we added something beyond existing.
-            const baseLen = existingPrompt ? 1 : 0;
-            if (parts.length > baseLen) {
-                return { systemPrompt: parts.join("\n\n") };
-            }
-        }
-        catch {
-            // best effort — never break agent start
-        }
-    });
-    // ── 4b. before_provider_response — capture response metadata ───
-    // Pi-2: Register the missing event so providers can record latency,
-    // model, and token usage when Pi exposes them. Best-effort only;
-    // the handler must never throw or modify the response.
-    pi.on("before_provider_response", (event) => {
-        try {
-            if (!_sessionId)
-                return;
-            const meta = {
-                model: event?.model ?? event?.providerModel,
-                provider: event?.provider,
-                latencyMs: event?.latencyMs ?? event?.latency,
-                tokens: event?.usage ?? event?.tokens,
-            };
-            // Skip when Pi gives us nothing useful — avoids noise in the DB.
-            if (meta.model == null &&
-                meta.provider == null &&
-                meta.latencyMs == null &&
-                meta.tokens == null) {
-                return;
-            }
-            const data = JSON.stringify(meta);
-            db.insertEvent(_sessionId, {
-                type: "provider_response",
-                category: "pi",
-                data,
-                priority: 1,
-                data_hash: createHash("sha256").update(data).digest("hex").slice(0, 16),
-            }, "PostToolUse");
-        }
-        catch {
-            // best effort — never break provider response
-        }
-    });
-    // ── 5. session_before_compact — Build resume snapshot ──
-    pi.on("session_before_compact", () => {
-        try {
-            if (!_sessionId)
-                return;
-            const allEvents = db.getEvents(_sessionId);
-            if (allEvents.length === 0)
-                return;
-            const stats = db.getSessionStats(_sessionId);
-            const snapshot = buildResumeSnapshot(allEvents, {
-                compactCount: (stats?.compact_count ?? 0) + 1,
-            });
-            db.upsertResume(_sessionId, snapshot, allEvents.length);
-        }
-        catch {
-            // best effort — never break compaction
-        }
-    });
-    // ── 6. session_compact — Increment compact counter ─────
-    pi.on("session_compact", () => {
-        try {
-            if (!_sessionId)
-                return;
-            db.incrementCompactCount(_sessionId);
-        }
-        catch {
-            // best effort
-        }
-    });
-    // ── 7. session_shutdown — Cleanup old sessions ─────────
-    pi.on("session_shutdown", () => {
-        try {
-            if (_db) {
-                _db.cleanupOldSessions(7);
-            }
-            _db = null;
-            _routingInjected.clear();
-            _sessionId = "";
-        }
-        catch {
-            // best effort — never throw during shutdown
-        }
-    });
-    // ── 8. Slash commands ──────────────────────────────────
-    pi.registerCommand("ctx-stats", {
-        description: "Show context-mode session statistics",
-        handler: async (argsOrCtx, maybeCtx) => {
-            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
-            const text = !_db || !_sessionId
-                ? "context-mode: no active session"
-                : buildStatsText(_db, _sessionId);
-            return handleCommandText(text, ctx);
-        },
-    });
-    pi.registerCommand("ctx-doctor", {
-        description: "Run context-mode diagnostics",
-        handler: async (argsOrCtx, maybeCtx) => {
-            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
-            const dbPath = getDBPath();
-            const dbExists = existsSync(dbPath);
-            const lines = [
-                "## ctx-doctor (Pi)",
-                "",
-                `- DB path: \`${dbPath}\``,
-                `- DB exists: ${dbExists}`,
-                `- Session ID: \`${_sessionId ? _sessionId.slice(0, 8) + "..." : "none"}\``,
-                `- Plugin root: \`${pluginRoot}\``,
-                `- Project dir: \`${projectDir}\``,
-            ];
-            if (_db && _sessionId) {
-                try {
-                    const stats = _db.getSessionStats(_sessionId);
-                    const eventCount = _db.getEventCount(_sessionId);
-                    lines.push(`- Events: ${eventCount}`);
-                    lines.push(`- Compactions: ${stats?.compact_count ?? 0}`);
-                    const resume = _db.getResume(_sessionId);
-                    lines.push(`- Resume snapshot: ${resume ? (resume.consumed ? "consumed" : "available") : "none"}`);
-                }
-                catch {
-                    lines.push("- DB query error");
-                }
-            }
-            const text = lines.join("\n");
-            return handleCommandText(text, ctx);
-        },
-    });
-}

package/build/routing-block.d.ts

@@ -1,8 +0,0 @@
-import type { ToolNamer } from "./tool-naming.js";
-export interface RoutingBlockOptions {
-    includeCommands?: boolean;
-}
-export declare function createRoutingBlock(t: ToolNamer, options?: RoutingBlockOptions): string;
-export declare function createReadGuidance(t: ToolNamer): string;
-export declare function createGrepGuidance(t: ToolNamer): string;
-export declare function createBashGuidance(t: ToolNamer): string;

package/build/routing-block.js

@@ -1,86 +0,0 @@
-export function createRoutingBlock(t, options = {}) {
-    const { includeCommands = true } = options;
-    return `
-<context_window_protection>
-  <priority_instructions>
-    Raw tool output floods context window. MUST use context-mode MCP tools. Keep raw data in sandbox.
-  </priority_instructions>
-
-  <tool_selection_hierarchy>
-    0. MEMORY: ${t("ctx_search")}(sort: "timeline")
-       - After resume, check prior context before asking user.
-    1. GATHER: ${t("ctx_batch_execute")}(commands, queries)
-       - Primary research tool. Runs commands, auto-indexes, searches. ONE call replaces many steps.
-       - Each command: {label: "section header", command: "shell command"}
-       - label becomes FTS5 chunk title — descriptive labels improve search.
-    2. FOLLOW-UP: ${t("ctx_search")}(queries: ["q1", "q2", ...])
-       - All follow-up questions. ONE call, many queries (default relevance mode).
-    3. PROCESSING: ${t("ctx_execute")}(language, code) | ${t("ctx_execute_file")}(path, language, code)
-       - API calls, log analysis, data processing.
-  </tool_selection_hierarchy>
-
-  <forbidden_actions>
-    - NO Bash for commands producing >20 lines output.
-    - NO Read for analysis — use execute_file. Read IS correct for files you intend to Edit.
-    - NO WebFetch — use ${t("ctx_fetch_and_index")}.
-    - Bash ONLY for git/mkdir/rm/mv/navigation.
-    - NO ${t("ctx_execute")} or ${t("ctx_execute_file")} for file creation/modification.
-      ctx_execute is for analysis, processing, computation only.
-  </forbidden_actions>
-
-  <file_writing_policy>
-    ALWAYS use native Write/Edit tools for file creation/modification.
-    NEVER use ${t("ctx_execute")}, ${t("ctx_execute_file")}, or Bash to write files.
-    Applies to all file types: code, configs, plans, specs, YAML, JSON, markdown.
-  </file_writing_policy>
-
-  <output_constraints>
-    <communication_style>
-      Terse like caveman. Technical substance exact. Only fluff die.
-      Use fragments when clear. Short synonyms (fix not "implement a solution for").
-      Technical terms exact. Code blocks unchanged.
-      Auto-expand for: security warnings, irreversible actions, user confusion.
-    </communication_style>
-    <artifact_policy>
-      Write artifacts (code, configs, PRDs) to FILES. NEVER inline.
-      Return only: file path + 1-line description.
-    </artifact_policy>
-    <response_format>
-      Concise summary:
-      - Actions taken (2-3 bullets)
-      - File paths created/modified
-      - Key findings
-    </response_format>
-  </output_constraints>
-  <session_continuity>
-    Skills, roles, and decisions set during this session remain active until the user revokes them.
-    Do not drop behavioral directives as context grows.
-  </session_continuity>
-${includeCommands ? `
-  <ctx_commands>
-    "ctx stats" | "ctx-stats" | "/ctx-stats" | context savings question
-    → Call stats MCP tool, display full output verbatim.
-
-    "ctx doctor" | "ctx-doctor" | "/ctx-doctor" | diagnose context-mode
-    → Call doctor MCP tool, run returned shell command, display as checklist.
-
-    "ctx upgrade" | "ctx-upgrade" | "/ctx-upgrade" | update context-mode
-    → Call upgrade MCP tool, run returned shell command, display as checklist.
-
-    "ctx purge" | "ctx-purge" | "/ctx-purge" | wipe/reset knowledge base
-    → Call purge MCP tool with confirm: true. Warn: irreversible.
-
-    After /clear or /compact: knowledge base preserved. Tell user: "context-mode knowledge base preserved. Use \`ctx purge\` to start fresh."
-  </ctx_commands>
-` : ''}
-</context_window_protection>`;
-}
-export function createReadGuidance(t) {
-    return '<context_guidance>\n  <tip>\n    Reading to Edit? Read is correct — Edit needs content in context.\n    Reading to analyze/explore? Use ' + t("ctx_execute_file") + '(path, language, code) — only printed summary enters context.\n  </tip>\n</context_guidance>';
-}
-export function createGrepGuidance(t) {
-    return '<context_guidance>\n  <tip>\n    May flood context. Use ' + t("ctx_execute") + '(language: "shell", code: "...") to run searches in sandbox. Only printed summary enters context.\n  </tip>\n</context_guidance>';
-}
-export function createBashGuidance(t) {
-    return '<context_guidance>\n  <tip>\n    May produce large output. Use ' + t("ctx_batch_execute") + '(commands, queries) for multiple commands, ' + t("ctx_execute") + '(language: "shell", code: "...") for single. Only printed summary enters context. Bash only for: git, mkdir, rm, mv, navigation.\n  </tip>\n</context_guidance>';
-}

package/build/runPool.d.ts

@@ -1,36 +0,0 @@
-/**
- * Generic in-flight-capped worker pool.
- *
- * Used by:
- *   - runBatchCommands (ctx_batch_execute parallel branch)
- *   - runBatchFetch    (ctx_fetch_and_index batch path)
- *
- * Returns Promise.allSettled-style results so one job's throw cannot
- * strand siblings. Caller maps fulfilled/rejected per index. Output
- * order is preserved by input index (not completion order).
- *
- * Designed to be the SINGLE concurrency primitive for the project —
- * all "run N independent operations with at most M in flight" needs
- * route here. Avoids the worker-pool copy-paste flagged in the
- * concurrency PRD architectural review (finding G).
- */
-export interface PoolJob<T> {
-    run(): Promise<T>;
-}
-export interface RunPoolOptions {
-    /** Hard concurrency cap (1-N). Auto-clamped to job count. */
-    concurrency: number;
-    /** Optional: also clamp by `os.cpus().length` (memory-pressure safety). Default false. */
-    capByCpuCount?: boolean;
-    /** Optional: per-settled callback (e.g. for progress reporting / metrics). */
-    onSettled?: (idx: number, result: PromiseSettledResult<unknown>) => void;
-}
-export interface RunPoolResult<T> {
-    /** Per-index settled result, ordered by input index. */
-    settled: PromiseSettledResult<T>[];
-    /** Concurrency actually used after all caps applied. */
-    effectiveConcurrency: number;
-    /** True when effectiveConcurrency < requested concurrency. */
-    capped: boolean;
-}
-export declare function runPool<T>(jobs: PoolJob<T>[], opts: RunPoolOptions): Promise<RunPoolResult<T>>;

package/build/runPool.js

@@ -1,51 +0,0 @@
-/**
- * Generic in-flight-capped worker pool.
- *
- * Used by:
- *   - runBatchCommands (ctx_batch_execute parallel branch)
- *   - runBatchFetch    (ctx_fetch_and_index batch path)
- *
- * Returns Promise.allSettled-style results so one job's throw cannot
- * strand siblings. Caller maps fulfilled/rejected per index. Output
- * order is preserved by input index (not completion order).
- *
- * Designed to be the SINGLE concurrency primitive for the project —
- * all "run N independent operations with at most M in flight" needs
- * route here. Avoids the worker-pool copy-paste flagged in the
- * concurrency PRD architectural review (finding G).
- */
-import { cpus } from "node:os";
-export async function runPool(jobs, opts) {
-    const { concurrency, capByCpuCount = false, onSettled } = opts;
-    if (jobs.length === 0) {
-        return { settled: [], effectiveConcurrency: 0, capped: false };
-    }
-    const requested = Math.max(1, concurrency);
-    const cpuCap = capByCpuCount ? Math.max(1, cpus().length) : requested;
-    const effectiveConcurrency = Math.min(requested, cpuCap, jobs.length);
-    const capped = effectiveConcurrency < requested;
-    const settled = new Array(jobs.length);
-    let nextIdx = 0;
-    async function worker() {
-        while (true) {
-            const idx = nextIdx++;
-            if (idx >= jobs.length)
-                return;
-            try {
-                const value = await jobs[idx].run();
-                settled[idx] = { status: "fulfilled", value };
-            }
-            catch (err) {
-                settled[idx] = { status: "rejected", reason: err };
-            }
-            onSettled?.(idx, settled[idx]);
-        }
-    }
-    const workers = [];
-    for (let w = 0; w < effectiveConcurrency; w++)
-        workers.push(worker());
-    // allSettled defends against any promise rejection escaping a worker
-    // (the worker already swallows its own errors, but this is belt-and-braces).
-    await Promise.allSettled(workers);
-    return { settled, effectiveConcurrency, capped };
-}