@pencil-agent/nano-pencil 1.13.16 → 1.14.1

package/README.md

@@ -127,7 +127,7 @@ nanopencil
 ```
 
 1. **Select your model** — Choose from available providers
-2. **Enter API key** — Securely stored in `~/.nanopencil/agent/auth.json`
+2. **Enter API key** — Securely stored in `~/.pencils/agents/default/auth.json`
 3. **Start coding** — Just type what you want to build
 
 ### Example Session

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.13.16",
-  "commitHash": "2949449",
-  "branch": "release-1.13.16",
-  "builtAt": "2026-05-09T13:16:34.096Z"
+  "version": "1.14.1",
+  "commitHash": "b4f6f24",
+  "branch": "main",
+  "builtAt": "2026-05-23T15:05:06.541Z"
 }

package/dist/builtin-extensions.js

@@ -23,11 +23,13 @@ const BUNDLED_LOOP_EXTENSION = join(__dirname, "extensions", "defaults", "loop",
 const BUNDLED_PLAN_EXTENSION = join(__dirname, "extensions", "defaults", "plan", "index.js");
 const BUNDLED_DIAGNOSTICS_EXTENSION = join(__dirname, "extensions", "defaults", "diagnostics", "index.js");
 const BUNDLED_SAL_EXTENSION = join(__dirname, "extensions", "defaults", "sal", "index.js");
+const BUNDLED_TOKEN_SAVE_EXTENSION = join(__dirname, "extensions", "defaults", "token-save", "index.js");
 const BUNDLED_GRUB_EXTENSION = join(__dirname, "extensions", "defaults", "grub", "index.js");
 const BUNDLED_SUBAGENT_EXTENSION = join(__dirname, "extensions", "defaults", "subagent", "index.js");
 const BUNDLED_TEAM_EXTENSION = join(__dirname, "extensions", "defaults", "team", "index.js");
 const BUNDLED_IDLE_THINK_EXTENSION = join(__dirname, "extensions", "defaults", "idle-think", "index.js");
 const BUNDLED_BTW_EXTENSION = join(__dirname, "extensions", "defaults", "btw", "index.js");
+const BUNDLED_RECAP_EXTENSION = join(__dirname, "extensions", "defaults", "recap", "index.js");
 const BUNDLED_DEBUG_EXTENSION = join(__dirname, "extensions", "defaults", "debug", "index.js");
 const BUNDLED_MCP_EXTENSION = join(__dirname, "extensions", "defaults", "mcp", "index.js");
 const BUNDLED_EXPORT_HTML_EXTENSION = join(__dirname, "extensions", "optional", "export-html", "index.js");
@@ -95,6 +97,15 @@ export function getBuiltinExtensionPaths() {
         if (existsSync(salTs))
             paths.push(salTs);
     }
+    // === TokenSave extension (default-on command output filtering and savings analytics) ===
+    if (existsSync(BUNDLED_TOKEN_SAVE_EXTENSION)) {
+        paths.push(BUNDLED_TOKEN_SAVE_EXTENSION);
+    }
+    else {
+        const tokenSaveTs = join(__dirname, "extensions", "defaults", "token-save", "index.ts");
+        if (existsSync(tokenSaveTs))
+            paths.push(tokenSaveTs);
+    }
     // === NanoMem extension ===
     // 1) Prefer extension bundled to dist/packages during build
     if (existsSync(BUNDLED_NANOMEM_EXTENSION_PACKAGES)) {
@@ -252,6 +263,15 @@ export function getBuiltinExtensionPaths() {
         if (existsSync(btwTs))
             paths.push(btwTs);
     }
+    // === Recap extension (on-demand ※ recap situational summaries) ===
+    if (existsSync(BUNDLED_RECAP_EXTENSION)) {
+        paths.push(BUNDLED_RECAP_EXTENSION);
+    }
+    else {
+        const recapTs = join(__dirname, "extensions", "defaults", "recap", "index.ts");
+        if (existsSync(recapTs))
+            paths.push(recapTs);
+    }
     // === Debug extension (system diagnostics with three-layer analysis) ===
     if (existsSync(BUNDLED_DEBUG_EXTENSION)) {
         paths.push(BUNDLED_DEBUG_EXTENSION);

package/dist/cli/args.d.ts

@@ -45,6 +45,8 @@ export interface Args {
     disableSoul?: boolean;
     /** Enable ACP (Agent Client Protocol) mode for editor integration */
     acp?: boolean;
+    /** Multi-Agent: ID of the agent to use. Default: "default" */
+    agent?: string;
     messages: string[];
     fileArgs: string[];
     /** Unknown flags (potentially extension flags) - map of flag name to value */

package/dist/cli/args.js

@@ -144,6 +144,9 @@ export function parseArgs(args, extensionFlags) {
         else if (arg === "--acp") {
             result.acp = true;
         }
+        else if (arg === "--agent" && i + 1 < args.length) {
+            result.agent = args[++i];
+        }
         else if (arg.startsWith("@")) {
             result.fileArgs.push(arg.slice(1)); // Remove @ prefix
         }
@@ -179,7 +182,8 @@ ${chalk.bold("Commands:")}
   ${APP_NAME} update [source]          Update installed extensions (skips pinned sources)
   ${APP_NAME} list                     List installed extensions from settings
   ${APP_NAME} config                   Open TUI to enable/disable package resources
-  ${APP_NAME} <command> --help         Show help for install/remove/update/list
+  ${APP_NAME} migrate                  Migrate data from legacy ~/.nanopencil to ~/.pencils
+  ${APP_NAME} <command> --help         Show help for commands
 
 ${chalk.bold("Options:")}
   --provider <name>              Provider name (default: google)
@@ -216,6 +220,7 @@ ${chalk.bold("Options:")}
   --disable-soul                 Disable Soul (AI personality evolution)
   --no-mcp                       Disable MCP (Model Context Protocol) tools
   --acp                         Run as ACP Agent (for editor integration)
+  --agent <id>                   Multi-Agent: Select a specific agent by ID (default: "default")
   --help, -h                     Show this help
   --version, -v                  Show version number
 

package/dist/config.d.ts

@@ -50,7 +50,7 @@ export declare const PACKAGE_NAME: string;
 export declare const ENV_AGENT_DIR: string;
 /** Get the share viewer URL for a gist ID */
 export declare function getShareViewerUrl(gistId: string): string;
-/** Get the agent config directory (e.g., ~/.nanopencil/agent/) */
+/** Get the agent config directory (e.g., ~/.pencils/agents/default/) */
 export declare function getAgentDir(): string;
 /** Get path to user's custom themes directory */
 export declare function getCustomThemesDir(): string;
@@ -72,7 +72,30 @@ export declare function getSessionsDir(): string;
 export declare function getDebugLogPath(): string;
 /** Get the root nanopencil config directory (e.g., ~/.nanopencil/) */
 export declare function getConfigRoot(): string;
-/** Get path to global browser-workspace directory (e.g., ~/.nanopencil/browser-workspace) */
+/**
+ * Resolve the Pencils ecosystem root directory.
+ * Priority: PENCILS_HOME > NANOPENCIL_HOME > ~/.pencils
+ *
+ * Design doc §3: only PENCILS_HOME is the canonical name;
+ * NANOPENCIL_HOME is a compat alias for existing users.
+ */
+export declare function getPencilsHome(): string;
+/** New Pencils agents root (e.g., ~/.pencils/agents/) */
+export declare function getPencilsAgentsDir(): string;
+/**
+ * Resolve an agent directory context for a given agent id.
+ * If no id is provided, returns the legacy single-agent context.
+ *
+ * Resolution order for per-agent path:
+ * 1. NANOPENCIL_CODING_AGENT_DIR env (legacy single-agent override)
+ * 2. PENCILS_AGENTS_DIR/<id> (new multi-agent path)
+ * 3. ~/.pencils/agents/<id> (default)
+ */
+export declare function resolveAgentDirContext(agentId?: string): {
+    id: string;
+    path: string;
+};
+/** Get path to global browser-workspace directory (e.g., ~/.pencils/workspaces/browser-workspace) */
 export declare function getBrowserWorkspaceDir(): string;
-/** Get path to global link-world-workspace directory (e.g., ~/.nanopencil/link-world-workspace) */
+/** Get path to global link-world-workspace directory (e.g., ~/.pencils/workspaces/link-world-workspace) */
 export declare function getLinkWorldWorkspaceDir(): string;

package/dist/config.js

@@ -168,20 +168,11 @@ export function getShareViewerUrl(gistId) {
     return `${baseUrl}#${gistId}`;
 }
 // =============================================================================
-// User Config Paths (~/.nanopencil/agent/*)
+// User Config Paths (~/.pencils/agents/default/*)
 // =============================================================================
-/** Get the agent config directory (e.g., ~/.nanopencil/agent/) */
+/** Get the agent config directory (e.g., ~/.pencils/agents/default/) */
 export function getAgentDir() {
-    const envDir = process.env[ENV_AGENT_DIR];
-    if (envDir) {
-        // Expand tilde to home directory
-        if (envDir === "~")
-            return homedir();
-        if (envDir.startsWith("~/"))
-            return homedir() + envDir.slice(1);
-        return envDir;
-    }
-    return join(homedir(), CONFIG_DIR_NAME, "agent");
+    return resolveAgentDirContext().path;
 }
 /** Get path to user's custom themes directory */
 export function getCustomThemesDir() {
@@ -240,11 +231,96 @@ export function getConfigRoot() {
     }
     return join(homedir(), CONFIG_DIR_NAME);
 }
-/** Get path to global browser-workspace directory (e.g., ~/.nanopencil/browser-workspace) */
+// =============================================================================
+// Multi-Agent: PENCILS_HOME & AgentDirContext support (N2)
+// =============================================================================
+/**
+ * Regex for a valid agent <id>.
+ * ASCII slug: lowercase alphanumeric start, then [a-z0-9._-], max 64 chars.
+ * Design doc §4.1.
+ */
+const AGENT_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Validate an agent id. Returns the id if valid, throws otherwise.
+ */
+function validateAgentId(id) {
+    if (!AGENT_ID_RE.test(id)) {
+        throw new Error(`Invalid agent id "${id}". Must match ${AGENT_ID_RE.source} (lowercase ASCII slug, max 64 chars).`);
+    }
+    return id;
+}
+/**
+ * Resolve the Pencils ecosystem root directory.
+ * Priority: PENCILS_HOME > NANOPENCIL_HOME > ~/.pencils
+ *
+ * Design doc §3: only PENCILS_HOME is the canonical name;
+ * NANOPENCIL_HOME is a compat alias for existing users.
+ */
+export function getPencilsHome() {
+    const envPencils = process.env.PENCILS_HOME;
+    if (envPencils) {
+        if (envPencils === "~")
+            return homedir();
+        if (envPencils.startsWith("~/"))
+            return homedir() + envPencils.slice(1);
+        return envPencils;
+    }
+    // Compat alias
+    const envNano = process.env.NANOPENCIL_HOME;
+    if (envNano) {
+        if (envNano === "~")
+            return homedir();
+        if (envNano.startsWith("~/"))
+            return homedir() + envNano.slice(1);
+        return envNano;
+    }
+    // Default: ~/.pencils (future target; for now fallback to legacy behavior)
+    return join(homedir(), ".pencils");
+}
+/** New Pencils agents root (e.g., ~/.pencils/agents/) */
+export function getPencilsAgentsDir() {
+    const envAgents = process.env.PENCILS_AGENTS_DIR;
+    if (envAgents) {
+        if (envAgents === "~")
+            return homedir();
+        if (envAgents.startsWith("~/"))
+            return homedir() + envAgents.slice(1);
+        return envAgents;
+    }
+    return join(getPencilsHome(), "agents");
+}
+/**
+ * Resolve an agent directory context for a given agent id.
+ * If no id is provided, returns the legacy single-agent context.
+ *
+ * Resolution order for per-agent path:
+ * 1. NANOPENCIL_CODING_AGENT_DIR env (legacy single-agent override)
+ * 2. PENCILS_AGENTS_DIR/<id> (new multi-agent path)
+ * 3. ~/.pencils/agents/<id> (default)
+ */
+export function resolveAgentDirContext(agentId) {
+    const id = agentId || "default";
+    validateAgentId(id);
+    // 1. Check legacy env override first (single-agent mode)
+    const envDir = process.env[ENV_AGENT_DIR];
+    if (envDir && id === "default") {
+        const resolvedEnv = envDir.startsWith("~/") ? homedir() + envDir.slice(1) : envDir;
+        return { id, path: resolvedEnv };
+    }
+    // 2. Check explicit per-agent env override
+    const envAgentsDir = process.env.PENCILS_AGENTS_DIR;
+    if (envAgentsDir) {
+        const base = envAgentsDir.startsWith("~/") ? homedir() + envAgentsDir.slice(1) : envAgentsDir;
+        return { id, path: join(base, id) };
+    }
+    // 3. Default multi-agent path under PENCILS_HOME
+    return { id, path: join(getPencilsHome(), "agents", id) };
+}
+/** Get path to global browser-workspace directory (e.g., ~/.pencils/workspaces/browser-workspace) */
 export function getBrowserWorkspaceDir() {
-    return join(getConfigRoot(), "browser-workspace");
+    return join(getConfigRoot(), "workspaces", "browser-workspace");
 }
-/** Get path to global link-world-workspace directory (e.g., ~/.nanopencil/link-world-workspace) */
+/** Get path to global link-world-workspace directory (e.g., ~/.pencils/workspaces/link-world-workspace) */
 export function getLinkWorldWorkspaceDir() {
-    return join(getConfigRoot(), "link-world-workspace");
+    return join(getConfigRoot(), "workspaces", "link-world-workspace");
 }

package/dist/core/agent-dir/agent-dir-context.d.ts

@@ -0,0 +1,60 @@
+/**
+ * [WHO]: AgentDirContext interface, defaultAgentDirContext(), agentDirContextOf(), validateAgentId()
+ * [FROM]: Depends on config.ts (getAgentDir)
+ * [TO]: Consumed by core/persona, core/session, core/soul-integration, core/mcp, extensions, future --agent flag
+ * [HERE]: core/agent-dir/agent-dir-context.ts - multi-agent directory abstraction
+ */
+/**
+ * Regex for a valid agent <id>.
+ * ASCII slug: lowercase alphanumeric start, then [a-z0-9._-], max 64 chars.
+ * Design doc §4.1.
+ */
+export declare const AGENT_ID_RE: RegExp;
+/**
+ * Validate an agent id. Returns the id if valid, throws otherwise.
+ */
+export declare function validateAgentId(id: string): string;
+export interface AgentOriginMetadata {
+    type: "local" | "cloud-adopted" | "imported";
+    asgard?: {
+        templateId: string;
+        templateVersion: string;
+        originUrl: string;
+        externalId: string;
+        lastSyncedAt: string;
+    };
+}
+/**
+ * Represents the resolved filesystem context for one agent.
+ *
+ * - `id`  : machine-readable slug (directory name, route key, Asgard externalId)
+ * - `path`: absolute path to the agent's data directory
+ * - `origin`: optional metadata if adopted from cloud (future, §4.2)
+ */
+export interface AgentDirContext {
+    /** Slug id, [a-z0-9._-]{1,64}; matches the directory name. Immutable once created. */
+    readonly id: string;
+    /** Absolute path; trusted to exist or be creatable. */
+    readonly path: string;
+    /** Optional — if the agent was adopted from cloud, the origin metadata. */
+    readonly origin?: AgentOriginMetadata;
+}
+/**
+ * Build the default context for the legacy single-agent path.
+ * This is the fallback when no `--agent` flag is provided.
+ * Resolves to whatever `getAgentDir()` returns today (~/.pencils/agents/default).
+ */
+export declare function defaultAgentDirContext(): AgentDirContext;
+/**
+ * Build an AgentDirContext for a specific agent id + resolved path.
+ * Throws if the id fails validation.
+ */
+export declare function agentDirContextOf(id: string, path: string, origin?: AgentOriginMetadata): AgentDirContext;
+/**
+ * Load AgentDirContext from an agent directory (loads agent.json if it exists).
+ */
+export declare function loadAgentDirContext(id: string): AgentDirContext;
+/**
+ * Save AgentDirContext to agent.json.
+ */
+export declare function saveAgentDirContext(ctx: AgentDirContext): void;

package/dist/core/agent-dir/agent-dir-context.js

@@ -0,0 +1,84 @@
+/**
+ * [WHO]: AgentDirContext interface, defaultAgentDirContext(), agentDirContextOf(), validateAgentId()
+ * [FROM]: Depends on config.ts (getAgentDir)
+ * [TO]: Consumed by core/persona, core/session, core/soul-integration, core/mcp, extensions, future --agent flag
+ * [HERE]: core/agent-dir/agent-dir-context.ts - multi-agent directory abstraction
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, getPencilsAgentsDir } from "../../config.js";
+// ---------------------------------------------------------------------------
+// ID validation
+// ---------------------------------------------------------------------------
+/**
+ * Regex for a valid agent <id>.
+ * ASCII slug: lowercase alphanumeric start, then [a-z0-9._-], max 64 chars.
+ * Design doc §4.1.
+ */
+export const AGENT_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Validate an agent id. Returns the id if valid, throws otherwise.
+ */
+export function validateAgentId(id) {
+    if (!AGENT_ID_RE.test(id)) {
+        throw new Error(`Invalid agent id "${id}". Must match ${AGENT_ID_RE.source} (lowercase ASCII slug, max 64 chars).`);
+    }
+    return id;
+}
+/**
+ * Build the default context for the legacy single-agent path.
+ * This is the fallback when no `--agent` flag is provided.
+ * Resolves to whatever `getAgentDir()` returns today (~/.pencils/agents/default).
+ */
+export function defaultAgentDirContext() {
+    return { id: "default", path: getAgentDir() };
+}
+/**
+ * Build an AgentDirContext for a specific agent id + resolved path.
+ * Throws if the id fails validation.
+ */
+export function agentDirContextOf(id, path, origin) {
+    validateAgentId(id);
+    return { id, path, origin };
+}
+/**
+ * Load AgentDirContext from an agent directory (loads agent.json if it exists).
+ */
+export function loadAgentDirContext(id) {
+    const path = join(getPencilsAgentsDir(), id);
+    const agentJsonPath = join(path, "agent.json");
+    if (existsSync(agentJsonPath)) {
+        try {
+            const content = readFileSync(agentJsonPath, "utf-8");
+            const metadata = JSON.parse(content);
+            return {
+                id: metadata.id || id,
+                path,
+                origin: metadata.origin,
+            };
+        }
+        catch {
+            // Fallback on parse error
+        }
+    }
+    // Default for agents under PENCILS_AGENTS_DIR
+    if (id !== "default" || existsSync(path)) {
+        return { id, path };
+    }
+    // Ultimate fallback to legacy default
+    return defaultAgentDirContext();
+}
+/**
+ * Save AgentDirContext to agent.json.
+ */
+export function saveAgentDirContext(ctx) {
+    if (!existsSync(ctx.path)) {
+        mkdirSync(ctx.path, { recursive: true });
+    }
+    const agentJsonPath = join(ctx.path, "agent.json");
+    const metadata = {
+        id: ctx.id,
+        origin: ctx.origin,
+    };
+    writeFileSync(agentJsonPath, JSON.stringify(metadata, null, 2), "utf-8");
+}

package/dist/core/agent-dir/agent-metadata.d.ts

@@ -0,0 +1,48 @@
+/**
+ * [WHO]: AgentMetadata interface, loadAgentMetadata(), saveAgentMetadata(), ensureAgentMetadata()
+ * [FROM]: Depends on agent-dir-context.ts, node:fs, node:path
+ * [TO]: Consumed by main.ts, future Gateway integration
+ * [HERE]: core/agent-dir/agent-metadata.ts - agent.json (machine-readable metadata)
+ *
+ * Design doc: docs/multi-agent-fs-design.md §4.2
+ */
+import type { AgentDirContext } from "./agent-dir-context.js";
+export interface AgentAsgardMetadata {
+    templateId: string;
+    templateVersion: string;
+    originUrl: string;
+    externalId: string;
+    lastSyncedAt: string;
+}
+export interface AgentMetadata {
+    version: string;
+    /** Slug id, [a-z0-9._-]{1,64}; matches the directory name. Immutable. */
+    id: string;
+    /** Human-readable name; can contain Chinese/emoji. */
+    displayName: string;
+    /** Human-readable description. */
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+    origin: {
+        type: "local" | "cloud-adopted" | "imported";
+        asgard?: AgentAsgardMetadata;
+    };
+    tags: string[];
+    engine: string;
+    extensions: Record<string, unknown>;
+}
+export declare const CURRENT_METADATA_VERSION = "1.0.0";
+/**
+ * Load agent.json from the agent directory.
+ * Returns undefined if the file does not exist or is invalid.
+ */
+export declare function loadAgentMetadata(agentDir: string): AgentMetadata | undefined;
+/**
+ * Save agent.json to the agent directory.
+ */
+export declare function saveAgentMetadata(agentDir: string, metadata: AgentMetadata): void;
+/**
+ * Ensure agent.json exists. If not, creates a default one based on context.
+ */
+export declare function ensureAgentMetadata(ctx: AgentDirContext): AgentMetadata;

package/dist/core/agent-dir/agent-metadata.js

@@ -0,0 +1,68 @@
+/**
+ * [WHO]: AgentMetadata interface, loadAgentMetadata(), saveAgentMetadata(), ensureAgentMetadata()
+ * [FROM]: Depends on agent-dir-context.ts, node:fs, node:path
+ * [TO]: Consumed by main.ts, future Gateway integration
+ * [HERE]: core/agent-dir/agent-metadata.ts - agent.json (machine-readable metadata)
+ *
+ * Design doc: docs/multi-agent-fs-design.md §4.2
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+export const CURRENT_METADATA_VERSION = "1.0.0";
+/**
+ * Load agent.json from the agent directory.
+ * Returns undefined if the file does not exist or is invalid.
+ */
+export function loadAgentMetadata(agentDir) {
+    const path = join(agentDir, "agent.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Save agent.json to the agent directory.
+ */
+export function saveAgentMetadata(agentDir, metadata) {
+    const path = join(agentDir, "agent.json");
+    if (!existsSync(agentDir)) {
+        mkdirSync(agentDir, { recursive: true });
+    }
+    metadata.updatedAt = new Date().toISOString();
+    writeFileSync(path, JSON.stringify(metadata, null, 2), "utf-8");
+}
+/**
+ * Ensure agent.json exists. If not, creates a default one based on context.
+ */
+export function ensureAgentMetadata(ctx) {
+    const existing = loadAgentMetadata(ctx.path);
+    if (existing) {
+        // Basic migration: ensure ID matches context (id is immutable)
+        if (existing.id !== ctx.id) {
+            existing.id = ctx.id;
+            saveAgentMetadata(ctx.path, existing);
+        }
+        return existing;
+    }
+    const now = new Date().toISOString();
+    const metadata = {
+        version: CURRENT_METADATA_VERSION,
+        id: ctx.id,
+        displayName: ctx.id === "default" ? "Default Agent" : ctx.id,
+        createdAt: now,
+        updatedAt: now,
+        origin: {
+            type: "local",
+        },
+        tags: [],
+        engine: "nano-pencil",
+        extensions: {},
+    };
+    saveAgentMetadata(ctx.path, metadata);
+    return metadata;
+}

package/dist/core/agent-dir/migration-tool.d.ts

@@ -0,0 +1,39 @@
+/**
+ * [WHO]: MigrationManager class, handleMigration()
+ * [FROM]: Depends on node:fs, node:path, node:os, chalk, config.ts
+ * [TO]: Consumed by main.ts (migrate command)
+ * [HERE]: core/agent-dir/migration-tool.ts - Safe copy-first migration from ~/.nanopencil to ~/.pencils
+ *
+ * Design doc: docs/multi-agent-fs-design.md §12.2
+ */
+export interface MigrationOptions {
+    dryRun: boolean;
+    apply: boolean;
+    copy: boolean;
+}
+export interface MigrationTask {
+    id: string;
+    source: string;
+    target: string;
+    label: string;
+    description: string;
+}
+export declare class MigrationManager {
+    private readonly legacyRoot;
+    private readonly newRoot;
+    private readonly migrationLogPath;
+    constructor();
+    run(options: MigrationOptions): Promise<void>;
+    /**
+     * Check if any migration is currently needed (legacy data exists and hasn't been migrated).
+     */
+    isMigrationNeeded(): boolean;
+    /**
+     * Run migration silently (no preview, direct apply) and return the list of migrated labels.
+     */
+    runSilent(): string[];
+    private plan;
+    private execute;
+    private isAlreadyApplied;
+    private logMigration;
+}