om-memory-system 4.13.3 → 4.14.1

package/README.md

@@ -1,197 +1,148 @@
+<p align="center">
+  <img src=".github/screenshots/omms-logo.png" alt="OMMS logo" width="96" height="96" />
+</p>
+
 # OMMS: Opinionated Modular Memory System
 
 [![npm version](https://img.shields.io/npm/v/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
 [![npm downloads](https://img.shields.io/npm/dm/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
-[![license](https://img.shields.io/npm/l/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
+[![MIT licence](https://img.shields.io/npm/l/om-memory-system.svg)](LICENSE.md)
+
+OMMS gives AI coding agents long-term project memory. It captures technical
+work, recalls relevant notes in later sessions and learns your working
+preferences. One shared engine serves **OpenCode**, **Pi** and **Claude Code**,
+so each host can retrieve memories captured by the others in the same project.
 
-![OMMS banner](.github/banner.png)
+Memories are stored locally, by default in `~/.omms/data`. Embeddings run
+locally by default; the first use downloads a search model. Capture and profile
+learning make additional model calls that can send conversation content to your
+chosen provider and incur costs. Remote embeddings are optional. OMMS removes
+text inside `<private>` tags before storage. See [Configuration](docs/configuration.md)
+for model choices and privacy controls.
 
-OMMS gives your AI coding agent a long-term memory. As you work, it writes
-short notes about what was done and decided in each project: fixes, design
-choices, things that did not work. It brings the relevant notes back in later
-sessions, so the agent does not start from zero every time. It also learns how
-you like to work and keeps that as a user profile.
+## Set up
 
-It runs inside [OpenCode](https://opencode.ai) and the
+Use Node.js **22.14 or later** for the terminal command and Claude Code hooks.
+OpenCode v1 needs **1.18.29 or later**. OMMS also supports OpenCode v2 and the
 [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
-Both share one memory per project, so a note written in one is available in
-the other. Everything is stored locally on your machine.
 
-Claude Code is also supported, through a plugin of hooks. It needs Node.js and
-your own external API for capture. A global install is optional. See the
-[Claude Code adapter](docs/claude-code-adapter.md) guide.
+> Automatic history import is enabled by default and makes model calls.
+> To disable it before your first session, set `"autoBackfill": false` in
+> `~/.config/omms/omms.jsonc`. See [Automatic import](docs/web-ui-memory.md#automatic-import).
 
-## What it does
+### OpenCode
 
-- **Remembers automatically.** After each piece of work, a background model
-  call summarises it into a memory. You do not have to ask.
-- **Recalls when relevant.** Matching memories are added to the agent's
-  context: on every prompt in OpenCode v2 and Pi, at the start of a session in
-  OpenCode v1.
-- **Learns your preferences.** A user profile of your habits builds up over
-  time and follows you across projects.
-- **Imports your past sessions.** Pi and OpenCode import older history after
-  startup. A command gives you a preview and manual control.
-- **Lets you look and edit.** A local web page shows every memory and your
-  profile.
-- **Keeps private things private.** Text inside `<private>` tags is never
-  stored.
+Add the package to `~/.config/opencode/opencode.json`. Keep your existing settings.
+On Windows, use `%USERPROFILE%\.config\opencode\opencode.json`.
 
-![Project memory timeline](.github/screenshot-project-memory.png)
+**OpenCode v2:**
 
-![User profile viewer](.github/screenshot-user-profile.png)
+```json
+{ "plugins": ["om-memory-system"] }
+```
 
-## Before you start
+**OpenCode v1:**
 
-You need one of:
+```json
+{ "plugin": ["om-memory-system"] }
+```
 
-- **OpenCode** 1.18.29 or later (v1 plugin API) or OpenCode v2
-- **Pi coding agent**
-- **Claude Code**, through a plugin of hooks. Capture needs your own external API. See
-  the [Claude Code adapter](docs/claude-code-adapter.md) guide for setup.
+OpenCode v2 also supports:
 
-Nothing else is required. OMMS brings its own database. On first use it
-downloads a small embedding model (the part that makes memories searchable),
-so you need internet access once. The terminal import command also needs
-Node.js 22.14 or later.
+```bash
+opencode plugin add om-memory-system
+```
 
-> [!NOTE]
-> OMMS is tested mostly on macOS and Linux. Windows runs only in the release
-> check, so it gets less testing. If something breaks on Windows,
-> [open an issue](https://github.com/cmdaltctr/omms/issues). If you fix it,
-> a pull request is welcome.
+Restart OpenCode. The [OpenCode guide](docs/opencode-adapter.md#installation)
+covers plugin management and its additional `cli.json` configuration.
 
-## Set up
+### Pi
 
-### 1. Install
+```bash
+pi install npm:om-memory-system
+```
 
-**OpenCode.** Add `om-memory-system` to `~/.config/opencode/opencode.json`
-(on Windows, `%USERPROFILE%\.config\opencode\opencode.json`):
+Restart Pi. See the [Pi guide](docs/pi-adapter.md).
 
-```jsonc
-// OpenCode v2
-{ "plugins": ["om-memory-system"] }
+### Claude Code
 
-// OpenCode v1
-{ "plugin": ["om-memory-system"] }
-```
+Install the OMMS plugin using the [Claude Code guide](docs/claude-code-adapter.md#installation).
+Capture and profile learning require a configured external API; retrieval and
+manual memory operations remain available without it. A global npm install is optional.
 
-On OpenCode v2 you can run `opencode plugin add om-memory-system` instead.
-Restart OpenCode.
+### Model and web app
 
-**Pi.** Run:
+With no model settings, OpenCode and Pi use the session model. You can choose a
+host model or configure an external API under **Settings**. Claude Code uses
+only the external API. See [Choosing the model](docs/configuration.md#choosing-the-model)
+for the selection order and credentials.
 
-```bash
-pi install npm:om-memory-system
-```
+Start a host session, then open [http://127.0.0.1:4747](http://127.0.0.1:4747).
+Each host starts the shared web app when needed, unless it is disabled. Browse
+captured notes on **Project memories**, or ask your agent to search memory for
+an earlier decision.
 
-Restart Pi. You can install OMMS in both agents; they share the same memory.
+### Terminal command (optional)
 
-**Terminal command (optional).** A global install puts the `om-memory-system`
-command on your `PATH`. You do not need it. OMMS runs the newest copy it finds on
-the machine, so updating one host is enough. A global install from 4.3 or earlier
-needs one update. See
-[Updating and upgrading](docs/upgrading.md#one-update-updates-every-host).
-To install it:
+A global install puts `om-memory-system` on your `PATH`:
 
 ```bash
-npm i -g om-memory-system      # or: bun add -g om-memory-system
+npm install -g om-memory-system
 om-memory-system --version
 ```
 
-### 2. Choose which model writes memories (optional)
-
-With no settings, OMMS uses the model of the session you are working in. To
-use a different one, add it to `~/.config/omms/omms.jsonc`. If you have no
-config file yet, OMMS creates this one with comments on first start.
-
-```jsonc
-{
-  // A model you are already signed in to in OpenCode or Pi.
-  // Use "inherit" to always follow the session's model.
-  "opencodeProvider": "openai",
-  "opencodeModel": "gpt-5.6-luna",
-  "piProvider": "openai-codex",
-  "piModel": "gpt-5.6-luna",
-}
-```
+See the [CLI reference](docs/cli.md) for manual memory operations and history imports.
 
-You can also use any OpenAI-compatible or Anthropic API with your own key, set
-up on the Settings page's **External API** card, and choose `"external"` as a
-host's model. See [Configuration](docs/configuration.md#choosing-the-model).
+## Inside OMMS
 
-### 3. Check it works
+These screenshots use synthetic examples and configuration. All visible prompts,
+code snippets and outcomes are made up for the demonstration.
 
-Work normally for a few turns, then open `http://127.0.0.1:4747` in your
-browser. OpenCode or the login web app serves this page. New memories appear
-on the timeline. You can also ask the agent: "search memory for what we changed today".
+### Project memories
 
-## Import your past history
+Browse captured notes alongside example user input and technical outcomes.
 
-Older sessions import automatically after a host starts. This makes model
-calls. To turn it off, set `"autoBackfill": false` in
-`~/.config/omms/omms.jsonc` before you start the agent. For a manual import or
-a custom source, preview it inside the agent:
+![Project memories with synthetic English prompts, code and outcomes](.github/screenshots/project-memories.png)
 
-```text
-/memory-import-opencode-history --dry-run
-/memory-import-pi-history --dry-run
-```
+### Memory
+
+Review history imports, manage profile learning and set memory limits. This page
+also helps resolve missing project folders.
+
+![Memory page with synthetic import and profile examples](.github/screenshots/memory.png)
+
+### Settings
+
+Choose models and manage access. Diagnostics show capture outcomes and component health.
 
-The preview shows how many model calls a real import needs. It uses the
-session's model; add `--model provider/id` for a cheaper one. There is also a
-terminal version, `npx om-memory-system`, that uses an API key. See the
-[OpenCode](docs/opencode-history-import.md) and [Pi](docs/pi-history-import.md)
-import guides, and the [CLI reference](docs/cli.md).
-
-## Keeping OMMS up to date
-
-Pi shows a notice when a new version is out; update with
-`pi update npm:om-memory-system`. On OpenCode v2, the footer shows when a new version is out;
-run `opencode plugin update om-memory-system`. Restart the agent afterwards.
-[UPDATES.md](UPDATES.md) explains how updates work on every host.
-To stay on one version, install it with the number, for example
-`pi install npm:om-memory-system@3.1.1` or
-`opencode plugin add om-memory-system@3.1.1`; a pinned install is never
-updated. Coming from `opencode-mem`? Your memories move over automatically, with a
-backup first. See [Updating and upgrading](docs/upgrading.md) and
-[CHANGELOG.md](CHANGELOG.md).
+![Settings page with synthetic model configuration](.github/screenshots/settings.png)
 
 ## Documentation
 
-| Read this                                                        | To learn about                                                   |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
-| [Using memory day to day](docs/using-memory.md)                  | How capture and recall work, the `memory` tool, the user profile |
-| [Configuration](docs/configuration.md)                           | Settings, choosing the model, embeddings, troubleshooting        |
-| [Web UI](docs/web-ui.md)                                         | The memory explorer, opening it on a network safely              |
-| [Settings page](docs/web-ui-settings.md)                         | Every card and control on the web Settings page                  |
-| [Moving projects](docs/moving-projects.md)                       | Nested repositories, moved folders, backup and restore           |
-| [Updating and upgrading](docs/upgrading.md)                      | Updates, pinning a version, older stores                         |
-| [OpenCode adapter](docs/opencode-adapter.md)                     | How the OpenCode plugin hooks in                                 |
-| [Pi adapter](docs/pi-adapter.md)                                 | How the Pi extension hooks in                                    |
-| [Claude Code adapter](docs/claude-code-adapter.md)               | Installing the Claude Code plugin, hooks, the `memory` command   |
-| [OpenCode history import](docs/opencode-history-import.md)       | Importing past OpenCode sessions                                 |
-| [Pi history import](docs/pi-history-import.md)                   | Importing past Pi sessions, moving machines                      |
-| [Claude Code history import](docs/claude-code-history-import.md) | Importing past Claude Code transcripts                           |
-| [CLI reference](docs/cli.md)                                     | The `om-memory-system` terminal command                          |
-| [Migrating from opencode-mem](docs/omms-migration.md)            | What changes when upgrading from the original plugin             |
-| [For developers](docs/developers.md)                             | Building, testing, the public `tags` export, architecture        |
-| [Contributing](CONTRIBUTING.md)                                  | How to set up, test, and send a pull request                     |
-
-## About this fork
-
-OMMS is [`cmdaltctr/omms`](https://github.com/cmdaltctr/omms), a fork of
-[`tickernelz/opencode-mem`](https://github.com/tickernelz/opencode-mem),
-published on npm as `om-memory-system`. The fork runs the memory engine as a
-shared core for both OpenCode and Pi (see [shared core](docs/shared-core.md)).
-Existing OpenCode memories and settings keep working.
-
-## License and links
-
-MIT License. See [LICENSE.md](LICENSE.md).
-
-- Repository: https://github.com/cmdaltctr/omms
-- Upstream: https://github.com/tickernelz/opencode-mem
-- Issues: https://github.com/cmdaltctr/omms/issues
-
-Inspired by [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory).
+| Guide                                       | Covers                                                       |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| [Using memory](docs/using-memory.md)        | Daily use, capture, recall and the user profile              |
+| [Web UI](docs/web-ui.md)                    | Starting the app, browsing memories and safe network access  |
+| [Memory page](docs/web-ui-memory.md)        | History imports, profile actions, limits and missing folders |
+| [Settings page](docs/web-ui-settings.md)    | Models, credentials, diagnostics and profile identities      |
+| [Configuration](docs/configuration.md)      | Config files, model selection, privacy and embeddings        |
+| [Moving projects](docs/moving-projects.md)  | Folder moves, backup and restore                             |
+| [Updating and upgrading](docs/upgrading.md) | Updates, version pinning and older stores                    |
+| [CLI reference](docs/cli.md)                | Terminal commands                                            |
+| [For developers](docs/developers.md)        | Building, testing and architecture                           |
+| [Contributing](CONTRIBUTING.md)             | Development workflow and pull requests                       |
+
+History import guides: [OpenCode](docs/opencode-history-import.md),
+[Pi](docs/pi-history-import.md) and [Claude Code](docs/claude-code-history-import.md).
+See [UPDATES.md](UPDATES.md) for host update commands and
+[CHANGELOG.md](CHANGELOG.md) for release changes. Existing `opencode-mem` users
+can follow the [migration guide](docs/omms-migration.md).
+
+## Licence
+
+MIT. See [LICENSE.md](LICENSE.md) for copyright and attribution, and
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for bundled dependencies.
+
+[Repository](https://github.com/cmdaltctr/omms) ·
+[Issues](https://github.com/cmdaltctr/omms/issues) ·
+[Documentation index](docs/README.md)

package/dist/importer/claude-import.js

@@ -58,6 +58,7 @@ export async function importClaudeHistory(deps, filters) {
             model: deps.profile.model,
             batchSize: deps.profile.batchSize,
             ...(deps.profile.onProgress ? { onProgress: deps.profile.onProgress } : {}),
+            ...(deps.profile.onEligiblePrompt ? { onEligiblePrompt: deps.profile.onEligiblePrompt } : {}),
         });
     }
     return report;

package/dist/importer/import-sessions.d.ts

@@ -27,6 +27,9 @@ export interface ImportMatchOptions {
     project?: string;
     pathMaps: ImportPathMap[];
     cwd: string;
+    /** Grouped imports can retain a valid source with no matching sessions as no-work. */
+    allowEmpty?: boolean;
+    signal?: AbortSignal;
 }
 export declare class StaleSelectionError extends Error {
     readonly status = 409;
@@ -91,6 +94,8 @@ export interface ResolvedImportSelection {
     identity: ImportSourceIdentity;
     keys: string[];
     cutoff: number;
+    /** Source sessions still missing a project, excluding ignored directories; never import keys. */
+    unresolvedCount?: number;
 }
 /**
  * Re-resolve a selection against the source right before a job. New sessions

package/dist/importer/import-sessions.js

@@ -39,7 +39,10 @@ async function readRows(identity, options, snapshotMode) {
         }));
     }
     const { openOpencodeHistory } = await import("./opencode-reader.js");
-    const history = await openOpencodeHistory(identity.realPath, {}, { shared: { key: importSourceKey(identity), mode: snapshotMode } });
+    const history = await openOpencodeHistory(identity.realPath, {}, {
+        shared: { key: importSourceKey(identity), mode: snapshotMode },
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
     try {
         return history.sessions.map((session) => ({
             key: session.sessionId,
@@ -71,6 +74,7 @@ function revisionOf(identity, options, projectTag, keys) {
         .digest("hex");
 }
 export async function matchImportSessions(identity, options, snapshotMode) {
+    options.signal?.throwIfAborted();
     assertImportSourceUnchanged(identity);
     const { projectFilterTag } = await import("./importer.js");
     const projectTag = options.scope === "current-project"
@@ -207,6 +211,7 @@ export function validateImportSelection(value) {
  * "ids" selection stale. Neither ever imports a session the user did not see.
  */
 export async function resolveImportSelection(sourceToken, selection, options) {
+    options.signal?.throwIfAborted();
     const identity = readImportSourceToken(sourceToken, options.host);
     const matched = await matchImportSessions(identity, options, "reuse").catch((error) => {
         if (error.code === "expired")
@@ -228,7 +233,14 @@ export async function resolveImportSelection(sourceToken, selection, options) {
         }
         keys = selection.sessions.map((item) => item.key);
     }
-    if (keys.length === 0)
+    if (keys.length === 0 && !options.allowEmpty)
         throw new Error("Choose sessions to import");
-    return { identity, keys, cutoff: selection.listedAt };
+    const { CONFIG } = await import("../config.js");
+    const { visibleUnresolvedCount } = await import("../services/backfill-state.js");
+    return {
+        identity,
+        keys,
+        cutoff: selection.listedAt,
+        unresolvedCount: visibleUnresolvedCount(matched.unresolved.length, matched.unresolved.map((row) => ({ directory: row.recordedDirectory ?? "", sessions: 1 })), CONFIG.importIgnoredDirectories ?? []),
+    };
 }

package/dist/importer/importer.d.ts

@@ -95,6 +95,7 @@ export interface ImporterDeps {
         model?: ModelPort;
         batchSize?: number;
         onProgress?: (done: number, total: number) => void;
+        onEligiblePrompt?: (identity: string) => void;
     };
 }
 export interface ImportWindow extends CaptureConversation {

package/dist/importer/importer.js

@@ -392,6 +392,7 @@ export async function importPiHistory(deps, filters) {
             model: deps.profile.model,
             batchSize: deps.profile.batchSize,
             ...(deps.profile.onProgress ? { onProgress: deps.profile.onProgress } : {}),
+            ...(deps.profile.onEligiblePrompt ? { onEligiblePrompt: deps.profile.onEligiblePrompt } : {}),
         });
     }
     return report;

package/dist/importer/opencode-import.d.ts

@@ -28,6 +28,7 @@ export interface OpencodeImportOptions {
     profileModel?: ModelPort;
     /** Profile batches done and planned, during the profile step. */
     onProfileProgress?: (done: number, total: number) => void;
+    onProfilePrompt?: (identity: string) => void;
     /** `alreadyHandled`: units found already done so far, which need no model call. */
     onProgress?: (processed: number, total: number, promptPreview: string, alreadyHandled?: number) => void;
     signal?: AbortSignal;

package/dist/importer/opencode-import.js

@@ -143,6 +143,7 @@ export async function importOpencodeHistory(options) {
                 batchSize: options.profileBatch,
                 model: options.profileModel,
                 ...(options.onProfileProgress ? { onProgress: options.onProfileProgress } : {}),
+                ...(options.onProfilePrompt ? { onEligiblePrompt: options.onProfilePrompt } : {}),
             });
         }
         return report;

package/dist/importer/profile-import.d.ts

@@ -28,6 +28,8 @@ export interface ProfileImportOptions {
     profileStore?: ProfileStore;
     /** Profile batches done and planned; called before the first batch and after each one. */
     onProgress?: (done: number, total: number) => void;
+    /** Dry-run estimate input only; no prompt content leaves this pipeline. */
+    onEligiblePrompt?: (identity: string) => void;
 }
 /** Record historical prompts and build or update the user profile in batches. */
 export declare function importProfileFromHistory(source: AsyncIterable<ImportSourceSession> | Iterable<ImportSourceSession>, options: ProfileImportOptions): Promise<ProfileImportReport>;

package/dist/importer/profile-import.js

@@ -7,6 +7,8 @@ import { buildImportKey } from "./importer.js";
 import { existsSync } from "node:fs";
 import { ImportLedger, importLedgerDbPath } from "./ledger.js";
 import { drainProfileBacklog } from "./profile-backlog.js";
+import { isTrivialPrompt } from "../core/trivial-prompt.js";
+import { profilePromptIdentity } from "./web-import-profile-estimate.js";
 /** Record historical prompts and build or update the user profile in batches. */
 export async function importProfileFromHistory(source, options) {
     if (!options.dryRun && !options.model)
@@ -62,6 +64,8 @@ export async function importProfileFromHistory(source, options) {
                 continue;
             }
             if (options.dryRun) {
+                if (!isTrivialPrompt(prompt))
+                    options.onEligiblePrompt?.(profilePromptIdentity(session.sessionId, unit.userEntryId));
                 report.promptsWouldRecord++;
                 continue;
             }

package/dist/importer/run-import.d.ts

@@ -18,6 +18,8 @@ export interface HistoryImportRun {
     signal?: AbortSignal;
     /** Profile batches done and planned, during the profile step after the exchanges. */
     onProfileProgress?: (done: number, total: number) => void;
+    /** Eligible dry-run profile prompt identities, kept out of public reports. */
+    onProfilePrompt?: (identity: string) => void;
     /** Record progress and take the host's lock for a run that calls models. */
     track?: {
         surface: ImportSurface;

package/dist/importer/run-import.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { profileFailureCode } from "../core/profile-failure.js";
 import { hostLabel } from "../types/host-label.js";
 const dryRunCapture = {
     summarize: async () => {
@@ -55,14 +56,20 @@ export async function runHistoryImport(host, args, run) {
                 },
             });
             const handled = report.unitsImported + report.unitsSkipped + report.unitsFailed;
-            await recorder.finish(recorder.pauseRequested ? "paused" : controller.signal.aborted ? "stopped" : "done", {
+            await recorder.finish(recorder.pauseRequested
+                ? "paused"
+                : controller.signal.aborted
+                    ? "stopped"
+                    : report.profile?.error
+                        ? "failed"
+                        : "done", {
                 // The total stays the one progress last reported; a real run has no
                 // "would import" count of its own.
                 done: handled,
                 imported: report.unitsImported,
                 skipped: report.unitsSkipped,
                 failed: report.unitsFailed,
-            });
+            }, report.profile?.error ? profileFailureCode(report.profile.error) : undefined);
             // Only a run over every project and every session sees the full list.
             if (args.scope === "all-projects" && !run.selection)
                 await recordUnresolved(host, report);
@@ -126,6 +133,7 @@ async function runUntracked(host, args, run) {
             ...(run.models.capture ? { provider: capture } : {}),
             ...(run.models.profile ? { profileModel: run.models.profile } : {}),
             ...(run.onProfileProgress ? { onProfileProgress: run.onProfileProgress } : {}),
+            ...(run.onProfilePrompt ? { onProfilePrompt: run.onProfilePrompt } : {}),
         });
     }
     const deps = {
@@ -138,6 +146,7 @@ async function runUntracked(host, args, run) {
                     ...(run.models.profile ? { model: run.models.profile } : {}),
                     ...(args.profileBatch ? { batchSize: args.profileBatch } : {}),
                     ...(run.onProfileProgress ? { onProgress: run.onProfileProgress } : {}),
+                    ...(run.onProfilePrompt ? { onEligiblePrompt: run.onProfilePrompt } : {}),
                 },
             }
             : {}),

package/dist/importer/web-import-group.d.ts

@@ -0,0 +1,57 @@
+import { type ImportHost } from "./import-args.js";
+import { type ImportReadiness } from "./import-readiness.js";
+import { resolveImportSelection } from "./import-sessions.js";
+import { type ImportSourceIdentity } from "./import-sources.js";
+import { runHistoryImport, summarizeHistoryImportReport, type HistoryImportRun } from "./run-import.js";
+import { type GroupImportRequest } from "./web-import-jobs.js";
+import { type ProfileEstimate } from "./web-import-profile-estimate.js";
+export type GroupHostState = "queued" | "running" | "done" | "failed" | "cancelled" | "no-work" | "not-run";
+type LegacySummary = ReturnType<typeof summarizeHistoryImportReport>;
+export type GroupImportSummary = Omit<LegacySummary, "profile"> & {
+    profile?: NonNullable<LegacySummary["profile"]> & {
+        promptsAlreadyHandled: number;
+    };
+};
+type Summary = GroupImportSummary;
+export interface GroupHostJob {
+    host: ImportHost;
+    state: GroupHostState;
+    sessions: number;
+    phase: "preparing" | "memory" | "profile";
+    processed: number;
+    total: number;
+    profileProcessed: number;
+    profileTotal: number;
+    summary?: Summary;
+    profileEstimate?: ProfileEstimate;
+    /** Model readiness for a real run, also visible in a read-only preview. */
+    blocker?: string;
+    error?: string;
+}
+export interface GroupImportJob {
+    id: string;
+    dryRun: boolean;
+    state: "running" | "cancelling" | "cancelled" | "done" | "failed";
+    activeHost?: ImportHost;
+    hosts: GroupHostJob[];
+    sessions: number;
+    processed: number;
+    total: number;
+    summary?: Summary;
+    profileEstimate?: ProfileEstimate;
+    error?: string;
+}
+export interface GroupImportDeps {
+    /** Model construction and store warmup, never invoked by a preview. */
+    prepareModels?: (choice: string, directory: string, signal: AbortSignal, host: ImportHost) => Promise<HistoryImportRun["models"]>;
+    discardSelection?: (identity: ImportSourceIdentity) => Promise<void>;
+    waitingPrompts?: () => Promise<Set<string>>;
+}
+type Deps = GroupImportDeps & {
+    runner: typeof runHistoryImport;
+    resolveSelection: typeof resolveImportSelection;
+    readiness: () => Promise<ImportReadiness>;
+};
+/** Preflight every child before launching a bounded sequential group in the existing slot. */
+export declare function startImportGroup(input: GroupImportRequest, directory: string, deps: Deps, publish: (job: GroupImportJob, controller: AbortController) => void): Promise<GroupImportJob>;
+export {};