@eyeauras/insight-cli 0.3.1 → 0.4.0

package/.cli-package-build.json

@@ -1 +1 @@
-{"version":1,"artifact":"197a094cb768427c71cf9790f11ce42ba4863f3892cc24e05c58e091347ffc3b"}
+{"version":1,"artifact":"034bd833a87d3a9c730b486252e2db09f67b3c6da2377c195389b894b26e12f7"}

package/SKILL.md

@@ -3,7 +3,7 @@ name: insight-cli
 description: Choose and prepare reverse-engineering capabilities from the insight-cli toolbox for binary, managed-code and runtime investigations. Use to discover the appropriate tool or its packaged skill before installing native runtimes.
 ---
 
-# insight-cli 0.3.1
+# insight-cli 0.4.0
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized
@@ -15,6 +15,9 @@ request/status recovery, never blind retry.
 Read the project's RE instructions and existing findings first. They own tool choices,
 evidence layout, formats and source of truth. These skills fill the remaining gaps.
 
+For repeated research calls, retain one [persistent CLI client](references/persistent.md)
+in the agent's long-lived runtime. Reuse it across calls to avoid repeated frontend startup.
+
 1. Run `insight-cli tools list --json` to discover the capabilities shipped in this version.
    The catalog works before profile configuration, downloads or IPC startup. A downloaded
    runtime is not needed to discover what a tool does.

package/dist/src/analysis-default.d.ts

@@ -0,0 +1,26 @@
+import { type CommandContext } from '@eyeauras/cli-factory';
+type Context = Pick<CommandContext, 'profile' | 'appArguments'>;
+export declare const analysisTrees: string[];
+export interface StorageDefault {
+    schema: 1;
+    base: string;
+    application: string;
+    binding: string;
+    id: string;
+    baseInode: string;
+    revision: string;
+}
+/** Storage control metadata, independent of Factory's profile/settings document. */
+export declare function storageDefault(c: Context): StorageDefault | undefined;
+export declare function validateStorageDefault(c: Context, value: StorageDefault): void;
+/** Preserve pre-existing local analysis until it is explicitly migrated. */
+export declare function legacyAnalysis(c: Context): boolean;
+export declare function inheritedStorage(c: Context): StorageDefault | undefined;
+export declare function checkStorageDefaultBase(c: Context, base: string): Promise<void>;
+export declare function writeStorageDefault(c: Context, base: string, revision?: string, expected?: string | null): Promise<{
+    state: 'configured' | 'superseded';
+    base: string | null;
+    revision: string | null;
+    binding?: StorageDefault;
+}>;
+export {};

package/dist/src/analysis-default.js

@@ -0,0 +1,149 @@
+import { CliError } from '@eyeauras/cli-factory';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { link, lstat, open, realpath, unlink } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { digest } from './model.js';
+import { atomicWrite, withToolLock } from './tool-runtime/store.js';
+export const analysisTrees = ['workspace', 'materials', 'temp', 'runtime'];
+const uuid = (value) => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value);
+const absent = (error) => error.code === 'ENOENT';
+function fail(code, message) { throw new CliError(message, { code: 'storage.' + code }); }
+const policyPath = (c) => join(c.appArguments.RoamingAppDataDirectory, '.analysis-storage-default.json');
+const markerPath = (base) => join(base, '.insight-storage-root.json');
+const binding = (c) => digest(realpathSync.native(c.appArguments.RoamingAppDataDirectory));
+function readOwnedJson(path) {
+    if (!lstatSync(path).isFile())
+        fail('configuration', 'Storage default metadata must be an ordinary file.');
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function valid(c, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return v.schema === 1 && v.application === c.appArguments.AppName && v.binding === binding(c) && uuid(v.id) &&
+        typeof v.base === 'string' && isAbsolute(v.base) && v.base === resolve(v.base) && !/[\0\r\n]/.test(v.base) &&
+        typeof v.baseInode === 'string' && /^\d+$/.test(v.baseInode);
+}
+/** Storage control metadata, independent of Factory's profile/settings document. */
+export function storageDefault(c) {
+    let value;
+    try {
+        value = readOwnedJson(policyPath(c));
+    }
+    catch (error) {
+        if (absent(error))
+            return;
+        fail('configuration', 'Installation storage default is unreadable; preserve its control metadata.');
+    }
+    if (!valid(c, value) || !uuid(value.revision))
+        fail('configuration', 'Installation storage default failed its application binding.');
+    return value;
+}
+export function validateStorageDefault(c, value) {
+    try {
+        if (!valid(c, value) || !uuid(value.revision))
+            throw Error('binding');
+        const st = lstatSync(value.base, { bigint: true }), marker = readOwnedJson(markerPath(value.base));
+        if (!st.isDirectory() || realpathSync.native(value.base) !== value.base || String(st.ino) !== value.baseInode ||
+            !valid(c, marker) || marker.id !== value.id || marker.base !== value.base || marker.baseInode !== value.baseInode)
+            throw Error('binding');
+    }
+    catch {
+        fail('unavailable', 'Installation analysis storage is missing or changed; mount its original volume. No fallback was created.');
+    }
+}
+/** Preserve pre-existing local analysis until it is explicitly migrated. */
+export function legacyAnalysis(c) {
+    return analysisTrees.some(tree => { try {
+        return !lstatSync(join(c.appArguments.AppDataDirectory, tree)).isSymbolicLink();
+    }
+    catch (error) {
+        if (absent(error))
+            return false;
+        throw error;
+    } });
+}
+export function inheritedStorage(c) {
+    if (c.profile.values.analysisDirectory !== undefined || legacyAnalysis(c))
+        return;
+    return storageDefault(c);
+}
+export async function checkStorageDefaultBase(c, base) {
+    let marker;
+    try {
+        marker = readOwnedJson(markerPath(base));
+    }
+    catch (error) {
+        if (absent(error))
+            return;
+        fail('binding', 'Storage base ownership metadata is unreadable; preserve it.');
+    }
+    if (!valid(c, marker) || marker.base !== base)
+        fail('binding', 'Storage base belongs to another application/control root; no data was adopted.');
+    const st = await lstat(base, { bigint: true });
+    if (!st.isDirectory() || await realpath(base) !== base || String(st.ino) !== marker.baseInode)
+        fail('binding', 'Storage base directory was replaced.');
+}
+export async function writeStorageDefault(c, base, revision = randomUUID(), expected) {
+    return withToolLock(c.appArguments.RoamingAppDataDirectory, 'analysis-storage-default', async () => {
+        const current = storageDefault(c);
+        if (current?.revision === revision) {
+            if (current.base !== base)
+                fail('binding', 'Storage default intent changed.');
+            validateStorageDefault(c, current);
+            return { state: 'configured', base, revision, binding: current };
+        }
+        // A resumed migration must never overwrite a later user's default selection.
+        if (expected !== undefined && (current?.revision ?? null) !== expected)
+            return { state: 'superseded', base: current?.base ?? null, revision: current?.revision ?? null };
+        const st = await lstat(base, { bigint: true });
+        if (!st.isDirectory() || await realpath(base) !== base)
+            fail('path', 'Choose an existing ordinary storage base directory.');
+        await checkStorageDefaultBase(c, base);
+        let marker;
+        try {
+            marker = readOwnedJson(markerPath(base));
+        }
+        catch (error) {
+            if (!absent(error))
+                throw error;
+            marker = { schema: 1, base, application: c.appArguments.AppName, binding: binding(c), id: randomUUID(), baseInode: String(st.ino) };
+            const temporary = markerPath(base) + '.new-' + randomUUID(), file = await open(temporary, 'wx', 0o600);
+            try {
+                try {
+                    await file.writeFile(JSON.stringify(marker) + '\n');
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                try {
+                    await link(temporary, markerPath(base));
+                }
+                catch (e) {
+                    if (e.code !== 'EEXIST')
+                        throw e;
+                }
+            }
+            finally {
+                await unlink(temporary);
+            }
+            await checkStorageDefaultBase(c, base);
+            marker = readOwnedJson(markerPath(base));
+        }
+        const next = { ...marker, revision };
+        validateStorageDefault(c, next);
+        if (process.platform !== 'win32') {
+            const dir = await open(base, 'r');
+            try {
+                await dir.sync();
+            }
+            finally {
+                await dir.close();
+            }
+        }
+        await atomicWrite(policyPath(c), next);
+        return { state: 'configured', base, revision, binding: next };
+    }, c.signal);
+}

package/dist/src/analysis-storage.d.ts

@@ -1,5 +1,6 @@
 import { type CommandContext, type CommandDefinition, type ProfileStoreContract } from '@eyeauras/cli-factory';
-export declare const analysisTrees: string[];
+import { type StorageDefault } from './analysis-default.js';
+export { analysisTrees } from './analysis-default.js';
 export declare function analysisDirectory(c: Pick<CommandContext, 'profile' | 'appArguments'>): string;
 /** Factory remains the only owner of profiles, settings, keyring and IPC admission. */
 export declare class AnalysisStorage {
@@ -16,6 +17,16 @@ export declare class AnalysisStorage {
     private save;
     private validate;
     wrap(entry: CommandDefinition): CommandDefinition;
+    private prepare;
+    private defaultBase;
+    setDefault(c: CommandContext, directory: unknown): Promise<{
+        defaultDirectory: string;
+        appliesTo: string;
+        state: "configured" | "superseded";
+        base: string | null;
+        revision: string | null;
+        binding?: StorageDefault;
+    }>;
     busy(directory: string): boolean;
     private exclusive;
     private preflight;
@@ -23,6 +34,7 @@ export declare class AnalysisStorage {
         profile: string;
         directory: string;
         configuration: string;
+        defaultBaseDirectory: string | null;
         defaultDirectory: string;
         availability: string;
         usage: unknown;
@@ -43,10 +55,20 @@ export declare class AnalysisStorage {
             progress: unknown;
         } | null;
     }>;
-    migrate(c: CommandContext, directory: unknown, dryRun?: boolean, emptyOnly?: boolean): Promise<{
+    migrate(c: CommandContext, directory: unknown, dryRun?: boolean, emptyOnly?: boolean, profileOnly?: boolean, automatic?: StorageDefault): Promise<{
+        state: "rolled_back";
+        id: string;
+        directory: string;
+        destinationRetained: string;
+    } | {
+        state: "cleaned";
+        id: string;
+        compatibilityPathsRetained: boolean;
+    } | {
         profile: string;
         directory: string;
         configuration: string;
+        defaultBaseDirectory: string | null;
         defaultDirectory: string;
         availability: string;
         usage: unknown;
@@ -66,21 +88,14 @@ export declare class AnalysisStorage {
             retainedSourceBytes: number;
             progress: unknown;
         } | null;
-    } | {
-        state: "rolled_back";
-        id: string;
-        directory: string;
-        destinationRetained: string;
-    } | {
-        state: "cleaned";
-        id: string;
-        compatibilityPathsRetained: boolean;
     } | {
         state: "committed" | "rolled_back" | "cleaned";
         id: string;
         directory: string;
         manifest: string;
         sourceRetained: boolean;
+        defaultBaseDirectory: string | null;
+        installationDefault: string;
         rollback: string;
         cleanup: string;
     } | {
@@ -96,13 +111,24 @@ export declare class AnalysisStorage {
         sourceRetained: boolean;
         compatibilityPathsRetained: boolean;
         state: string;
+        setsInstallationDefault: boolean;
     }>;
     private checkCopy;
     private continue;
     resume(c: CommandContext): Promise<{
+        state: "rolled_back";
+        id: string;
+        directory: string;
+        destinationRetained: string;
+    } | {
+        state: "cleaned";
+        id: string;
+        compatibilityPathsRetained: boolean;
+    } | {
         profile: string;
         directory: string;
         configuration: string;
+        defaultBaseDirectory: string | null;
         defaultDirectory: string;
         availability: string;
         usage: unknown;
@@ -122,21 +148,14 @@ export declare class AnalysisStorage {
             retainedSourceBytes: number;
             progress: unknown;
         } | null;
-    } | {
-        state: "rolled_back";
-        id: string;
-        directory: string;
-        destinationRetained: string;
-    } | {
-        state: "cleaned";
-        id: string;
-        compatibilityPathsRetained: boolean;
     } | {
         state: "committed" | "rolled_back" | "cleaned";
         id: string;
         directory: string;
         manifest: string;
         sourceRetained: boolean;
+        defaultBaseDirectory: string | null;
+        installationDefault: string;
         rollback: string;
         cleanup: string;
     }>;

package/dist/src/analysis-storage.js

@@ -7,10 +7,11 @@ import { atomicWrite, readJson, toolProfileBusy } from './tool-runtime/store.js'
 import { listProcesses } from './tool-runtime/supervisor.js';
 import { runtimeProcesses } from './runtime-manager.js';
 import { digest } from './model.js';
+import { analysisTrees, inheritedStorage, legacyAnalysis, storageDefault, validateStorageDefault, checkStorageDefaultBase, writeStorageDefault } from './analysis-default.js';
+export { analysisTrees } from './analysis-default.js';
 // Move the complete runtime tree too: installation stages must share a filesystem with
 // installations, and both native checks and process runs can contain large generated DBs.
 // Stable aliases preserve references in immutable native journals, selections and results.
-export const analysisTrees = ['workspace', 'materials', 'temp', 'runtime'];
 const terminal = (state) => ['committed', 'rolled_back', 'cleaned'].includes(state);
 const inside = (parent, child) => { const r = relative(parent, child); return r === '' || !isAbsolute(r) && r !== '..' && !r.startsWith('..' + sep); };
 function fail(code, message) { throw new CliError(message, { code: 'storage.' + code }); }
@@ -37,8 +38,12 @@ async function sync(path, directory = false) {
 }
 export function analysisDirectory(c) {
     const value = c.profile.values.analysisDirectory;
-    if (value === undefined || value === null)
+    if (value === null)
         return c.appArguments.AppDataDirectory;
+    if (value === undefined) {
+        const shared = storageDefault(c);
+        return shared && !legacyAnalysis(c) ? join(shared.base, c.appArguments.AppName, c.profile.name) : c.appArguments.AppDataDirectory;
+    }
     if (typeof value !== 'string' || !isAbsolute(value) || value !== resolve(value))
         fail('configuration', 'Invalid analysis directory in the Factory profile.');
     return value;
@@ -140,6 +145,9 @@ export class AnalysisStorage {
             !isAbsolute(j.source) || !isAbsolute(j.destination) || inside(j.source, j.destination) || inside(j.destination, j.source) ||
             !isAbsolute(j.destinationAnchor) || !inside(j.destinationAnchor, j.destination) || typeof j.sourceIdentity !== 'string' || typeof j.destinationIdentity !== 'string' ||
             !['copying', 'verified', 'activating', 'committed', 'rolling_back', 'rolled_back', 'cleaning', 'cleaned'].includes(j.state) ||
+            ['automatic', 'makeDefault', 'defaultApplied', 'defaultSuperseded'].some(k => { const v = j[k]; return v !== undefined && typeof v !== 'boolean'; }) ||
+            j.defaultPreviousRevision !== undefined && j.defaultPreviousRevision !== null && !/^[-a-f0-9]{36}$/.test(j.defaultPreviousRevision) ||
+            j.automatic && (!j.defaultBinding || j.makeDefault || j.files !== 0 || j.bytes !== 0 || loadEntries && j.entries.length !== 0) ||
             !Array.isArray(j.trees) || j.trees.some(t => !analysisTrees.includes(t)) || !Array.isArray(j.entries) ||
             j.entries.some(e => !j.trees.some(t => e.path === t || e.path.startsWith(t + '/')) || e.path.split('/').some(p => p === '..' || p === '.' || p === '')) ||
             !/^[a-f0-9]{64}$/.test(j.manifest) || loadEntries && j.manifest !== digest(content(j.entries)))
@@ -153,7 +161,7 @@ export class AnalysisStorage {
         const { entries, ...record } = j;
         await atomicWrite(join(this.control(c), 'migration.json'), record);
     }
-    async validate(c) {
+    async validate(c, initializing = false) {
         const root = analysisDirectory(c), j = await this.journal(c);
         if (j && !terminal(j.state))
             fail('pending', 'Migration is incomplete. Use storage show, resume or rollback before research.');
@@ -161,6 +169,12 @@ export class AnalysisStorage {
             fail('configuration', 'Factory profile and committed migration differ; preserve both and inspect storage show.');
         if (root === c.appArguments.AppDataDirectory)
             return;
+        const shared = inheritedStorage(c);
+        if (shared && !j) {
+            if (!initializing)
+                validateStorageDefault(c, shared);
+            return;
+        }
         const marker = await readJson(join(root, '.insight-analysis.json'));
         if (!marker || marker.schema !== 1 || marker.binding !== await this.binding(c) || await realpath(root) !== root)
             fail('unavailable', 'Configured analysis storage is missing or changed; mount its volume. No fallback was created.');
@@ -175,12 +189,15 @@ export class AnalysisStorage {
         const run = entry.run;
         return { ...entry, ...(entry.children ? { children: entry.children.map(e => this.wrap(e)) } : {}), ...(run ? { run: async (input, c) => {
                     const key = c.appArguments.AppDataDirectory;
+                    if (this.changing.has(key))
+                        fail('busy', 'Storage migration is in progress.');
+                    const prepared = await this.prepare(c);
                     if (this.changing.has(key))
                         fail('busy', 'Storage migration is in progress.');
                     this.active.set(key, (this.active.get(key) ?? 0) + 1);
                     try {
-                        await this.validate(c);
-                        return await run(input, c);
+                        await this.validate(prepared);
+                        return await run(input, prepared);
                     }
                     finally {
                         const n = this.active.get(key) - 1;
@@ -191,6 +208,42 @@ export class AnalysisStorage {
                     }
                 } } : {}) };
     }
+    async prepare(c) {
+        const j = await this.journal(c), shared = inheritedStorage(c);
+        if (j?.automatic && !['cleaned', 'rolled_back'].includes(j.state)) {
+            await this.resume(c);
+            c = { ...c, profile: await this.store(c).get(c.profile.name) };
+        }
+        else if (!j && shared) {
+            validateStorageDefault(c, shared);
+            await this.migrate(c, shared.base, false, true, true, shared);
+            c = { ...c, profile: await this.store(c).get(c.profile.name) };
+        }
+        // One command keeps its selected root even if another profile changes the default.
+        return { ...c, profile: { ...c.profile, values: { ...c.profile.values, analysisDirectory: analysisDirectory(c) } } };
+    }
+    async defaultBase(c, directory, existingOnly = false) {
+        if (typeof directory !== 'string' || !isAbsolute(directory) || /[\0\r\n]/.test(directory))
+            fail('path', 'Supply an absolute destination base directory.');
+        const base = await canonicalFuture(resolve(directory)), app = await canonicalFuture(c.appArguments.RoamingAppDataDirectory);
+        if (inside(app, base) || inside(base, app))
+            fail('path', 'The installation storage base and Factory configuration root must be separate, non-nested directories.');
+        for (const profile of (await this.store(c).list()).profiles) {
+            if (typeof profile.values.analysisDirectory !== 'string')
+                continue;
+            const root = await canonicalFuture(profile.values.analysisDirectory);
+            if (inside(root, base))
+                fail('path', 'The installation storage base cannot be nested inside a profile analysis directory.');
+        }
+        if (existingOnly && !await present(base))
+            fail('path', 'Choose an existing mounted storage base directory.');
+        await checkStorageDefaultBase(c, base);
+        return base;
+    }
+    async setDefault(c, directory) {
+        const base = await this.defaultBase(c, directory, true), result = await writeStorageDefault(c, base);
+        return { ...result, defaultDirectory: join(base, c.appArguments.AppName, c.profile.name), appliesTo: 'new and empty profiles; initialized profile locations are preserved' };
+    }
     busy(directory) { return this.changing.has(directory); }
     async exclusive(c, action) {
         const key = c.appArguments.AppDataDirectory;
@@ -212,7 +265,7 @@ export class AnalysisStorage {
     async preflight(c, directory) {
         if (typeof directory !== 'string' || !isAbsolute(directory) || /[\0\r\n]/.test(directory))
             fail('path', 'Supply an absolute destination base directory.');
-        const source = await canonicalFuture(analysisDirectory(c)), destination = await canonicalFuture(join(resolve(directory), c.appArguments.AppName, c.profile.name));
+        const source = await canonicalFuture(inheritedStorage(c) ? c.appArguments.AppDataDirectory : analysisDirectory(c)), destination = await canonicalFuture(join(resolve(directory), c.appArguments.AppName, c.profile.name));
         const app = await canonicalFuture(c.appArguments.RoamingAppDataDirectory);
         if (inside(source, destination) || inside(destination, source) || inside(app, destination) || inside(destination, app))
             fail('path', 'Source, destination and profile configuration roots must be separate, non-nested directories.');
@@ -235,7 +288,7 @@ export class AnalysisStorage {
         return { source, destination, destinationAnchor: parent, destinationIdentity: await directoryIdentity(parent), bytes, entries: entries.length, availableBytes: available.toString(), requiredBytes: (BigInt(bytes) + reserve).toString(), trees: analysisTrees, sourceRetained: true, compatibilityPathsRetained: true };
     }
     async show(c) {
-        const j = await this.journal(c), root = analysisDirectory(c);
+        const j = await this.journal(c), root = analysisDirectory(c), shared = storageDefault(c);
         let usage, availability = 'available';
         try {
             await this.validate(c);
@@ -245,23 +298,34 @@ export class AnalysisStorage {
         catch (error) {
             availability = error instanceof CliError ? error.code : (error.code ?? 'unavailable');
         }
-        return { profile: c.profile.name, directory: root, configuration: 'Factory profile analysisDirectory', defaultDirectory: c.appArguments.AppDataDirectory, availability, usage,
+        return { profile: c.profile.name, directory: root, configuration: c.profile.values.analysisDirectory !== undefined ? 'Factory profile analysisDirectory' : shared && root !== c.appArguments.AppDataDirectory ? 'Installation storage default' : 'Factory profile AppData', defaultBaseDirectory: shared?.base ?? null, defaultDirectory: shared ? join(shared.base, c.appArguments.AppName, c.profile.name) : c.appArguments.AppDataDirectory, availability, usage,
             trees: analysisTrees, appData: c.appArguments.AppDataDirectory, included: ['snapshots, immutable inputs, native projects and local server repositories', 'tool execution/verification working data', 'runtime installations, acquisition caches, selections and process receipts'], excluded: ['profiles, permissions, IPC, logs and OS keyring secrets'],
             migration: j ? { id: j.id, state: j.state, source: j.source, destination: j.destination, manifest: j.manifest, bytes: j.bytes, files: j.files, retainedSource: join(j.source, '.storage-retained', j.id), retainedSourceBytes: j.state === 'committed' ? j.bytes : 0, progress: await readJson(join(this.control(c), 'progress.json')) } : null };
     }
-    async migrate(c, directory, dryRun = false, emptyOnly = false) {
+    async migrate(c, directory, dryRun = false, emptyOnly = false, profileOnly = false, automatic) {
         return this.exclusive(c, async () => {
-            await this.validate(c);
+            await this.validate(c, true);
+            if (automatic)
+                validateStorageDefault(c, automatic);
             const plan = await this.preflight(c, directory);
+            if (automatic) {
+                validateStorageDefault(c, automatic);
+                if (plan.destination !== join(automatic.base, c.appArguments.AppName, c.profile.name))
+                    fail('binding', 'Automatic initialization changed its destination.');
+            }
+            if (!profileOnly)
+                await this.defaultBase(c, directory);
             if (dryRun)
-                return { state: 'preflight', ...plan };
+                return { state: 'preflight', setsInstallationDefault: !profileOnly, ...plan };
             if (emptyOnly && plan.entries)
                 fail('data', 'This profile already has analysis data. Use storage migrate --directory to preserve it.');
             const entries = await inventory(plan.source, analysisTrees, true, c.signal), id = randomUUID();
+            if (emptyOnly && entries.length)
+                fail('data', 'Analysis appeared during empty-profile initialization; no migration was started.');
             const binding = await this.binding(c);
             const j = { schema: 1, id, profile: c.profile.name, binding, source: plan.source, destination: plan.destination,
                 sourceIdentity: await directoryIdentity(plan.source), destinationAnchor: plan.destinationAnchor, destinationIdentity: plan.destinationIdentity,
-                previous: typeof c.profile.values.analysisDirectory === 'string' ? c.profile.values.analysisDirectory : null, state: 'copying', entries, trees: [...analysisTrees], manifest: digest(content(entries)), createdAt: new Date().toISOString(), bytes: entries.reduce((n, e) => n + e.size, 0), files: entries.filter(e => e.kind === 'file').length };
+                previous: typeof c.profile.values.analysisDirectory === 'string' ? c.profile.values.analysisDirectory : null, automatic: Boolean(automatic), defaultBinding: automatic, makeDefault: !profileOnly, defaultPreviousRevision: storageDefault(c)?.revision ?? null, state: 'copying', entries, trees: [...analysisTrees], manifest: digest(content(entries)), createdAt: new Date().toISOString(), bytes: entries.reduce((n, e) => n + e.size, 0), files: entries.filter(e => e.kind === 'file').length };
             // Reserve durably before any destination or source changes. All ordinary commands now freeze.
             await this.save(c, j);
             await this.checkpoint?.('reserved');
@@ -282,12 +346,35 @@ export class AnalysisStorage {
             fail('volume', 'A migration volume changed or disappeared. Mount the original volume before resuming; no fallback was created.');
         if (await canonicalFuture(j.destination) !== j.destination || j.targetIdentity && await directoryIdentity(j.destination) !== j.targetIdentity)
             fail('binding', 'Destination directory was replaced; no migration write was made.');
+        if (j.defaultBinding)
+            validateStorageDefault(c, j.defaultBinding);
+        if (j.defaultBaseIdentity && await directoryIdentity(dirname(dirname(j.destination))) !== j.defaultBaseIdentity)
+            fail('volume', 'The selected storage base directory was replaced.');
         if (j.state === 'rolling_back')
             return this.restore(c, j);
         if (j.state === 'cleaning')
             return this.finishCleanup(c, j);
-        if (terminal(j.state))
+        if (terminal(j.state) && !(j.automatic && j.state === 'committed'))
             return this.show(c);
+        if (j.makeDefault && !j.defaultApplied) {
+            const base = dirname(dirname(j.destination));
+            if (await canonicalFuture(base) !== base)
+                fail('binding', 'Storage default base was replaced.');
+            await mkdir(base, { recursive: true, mode: 0o700 });
+            if (await directoryIdentity(j.destinationAnchor) !== j.destinationIdentity)
+                fail('volume', 'The default storage volume changed.');
+            if (!j.defaultBaseIdentity) {
+                j.defaultBaseIdentity = await directoryIdentity(base);
+                await this.save(c, j);
+            }
+            const result = await writeStorageDefault(c, base, j.id, j.defaultPreviousRevision ?? null);
+            await this.checkpoint?.('default-selected');
+            j.defaultApplied = true;
+            j.defaultSuperseded = result.state === 'superseded';
+            if (!j.defaultSuperseded)
+                j.defaultBinding = result.binding;
+            await this.save(c, j);
+        }
         if (j.state === 'copying') {
             await privateDirectory(j.destination);
             if (!j.targetIdentity) {
@@ -439,7 +526,14 @@ export class AnalysisStorage {
             await this.save(c, j);
             await atomicWrite(join(this.control(c), 'progress.json'), { completed: j.entries.length, total: j.entries.length, phase: 'committed' });
         }
-        return { state: j.state, id: j.id, directory: j.destination, manifest: j.manifest, sourceRetained: true, rollback: 'storage rollback', cleanup: 'storage cleanup' };
+        if (j.automatic && j.state === 'committed') {
+            if (j.entries.length)
+                fail('binding', 'Automatic profile initialization cannot delete existing analysis.');
+            j.state = 'cleaning';
+            await this.save(c, j);
+            return this.finishCleanup(c, j);
+        }
+        return { state: j.state, id: j.id, directory: j.destination, manifest: j.manifest, sourceRetained: true, defaultBaseDirectory: storageDefault(c)?.base ?? null, installationDefault: j.makeDefault ? (j.defaultSuperseded ? 'superseded' : 'configured') : 'unchanged', rollback: 'storage rollback', cleanup: 'storage cleanup' };
     }
     async resume(c) { return this.exclusive(c, async () => { const j = await this.journal(c, true); if (!j)
         fail('missing', 'No migration journal exists.'); return this.continue(c, j); }); }
@@ -549,11 +643,13 @@ export class AnalysisStorage {
             fail('binding', 'Retained source directory was replaced; no deletion or restore was attempted.');
     }
     commands() {
+        const profileOnly = { flags: '--profile-only', description: 'Keep the installation default unchanged; move only this profile' };
         const directory = { flags: '--directory <path>', description: 'Absolute base directory; app name and profile are appended', required: true };
         return command('storage', 'Inspect and migrate profile analysis data', [
             command('show', 'Show effective analysis storage, usage and retained migration', (_i, c) => this.show(c), { permission: Permission.ReadOnly }),
-            command('configure', 'Choose storage for a profile with no analysis data', ({ options: o }, c) => this.migrate(c, o.directory, false, true), { permission: Permission.Update, options: [directory] }),
-            command('migrate', 'Copy and verify all analysis data, retain source, then switch storage', ({ options: o }, c) => this.migrate(c, o.directory, Boolean(o.dryRun)), { permission: Permission.Update, options: [directory, { flags: '--dry-run', description: 'Read-only path, capacity and quiescence preflight; create no migration' }] }),
+            command('default', 'Set the installation storage base for new profiles; preserve existing data locations', ({ options: o }, c) => this.setDefault(c, o.directory), { permission: Permission.Update, options: [directory] }),
+            command('configure', 'Choose storage for an empty profile and subsequent new profiles', ({ options: o }, c) => this.migrate(c, o.directory, false, true, Boolean(o.profileOnly)), { permission: Permission.Update, options: [directory, profileOnly] }),
+            command('migrate', 'Copy and verify all analysis data, retain source, then switch storage', ({ options: o }, c) => this.migrate(c, o.directory, Boolean(o.dryRun), false, Boolean(o.profileOnly)), { permission: Permission.Update, options: [directory, profileOnly, { flags: '--dry-run', description: 'Read-only path, capacity and quiescence preflight; create no migration' }] }),
             command('resume', 'Resume the retained copy/activation or rollback without replaying research', (_i, c) => this.resume(c), { permission: Permission.Update }),
             command('rollback', 'Restore retained source; refuse after any destination content changes', (_i, c) => this.rollback(c), { permission: Permission.Update }),
             command('cleanup', 'Delete verified retained source copies; retain compatibility paths permanently', (_i, c) => this.cleanup(c), { permission: 'Destructive' }),

package/dist/src/arguments.js

@@ -23,8 +23,10 @@ export function parsed(p, value) {
             fail('invalid', `${flag(p.name)} is outside its supported query range.`);
         if (p.name === 'timeout_seconds' && (result < 1 || result > 1800))
             fail('invalid', 'timeout-seconds must be between 1 and 1800.');
-        if (p.name === 'max_scan' && (result < 1 || result > 200000) || p.name === 'max_bytes' && (result < 1 || result > 16777216))
-            fail('invalid', `${flag(p.name)} is outside its supported work budget.`);
+        if (p.name === 'max_scan' && (result < 1 || result > 200000))
+            fail('invalid', 'max-scan must be between 1 and 200000 visited inputs; result offset does not advance scan coverage.');
+        if (p.name === 'max_bytes' && (result < 1 || result > 16777216))
+            fail('invalid', 'max-bytes must be between 1 and 16777216 bytes.');
         return result;
     }
     if (['json', 'object', 'array', 'any'].includes(p.type)) {
@@ -55,8 +57,11 @@ export function option(p) {
     const value = p.default;
     const defaultValue = value === undefined || value === '' && !p.allowEmpty ? undefined : parsed(p, value);
     return { flags: `--${flag(p.name)} <${p.type === 'json' ? 'json' : p.type}>`,
-        description: p.semantic === 'function_ref' ? 'Function name or explicit address' : p.semantic === 'address' ? 'Explicit hexadecimal address' :
-            `${flag(p.name)} (${p.type}${p.name === 'limit' ? ', 1–1000' : p.name === 'length' ? ', 1–65536 bytes' : ''})`,
+        description: p.name === 'max_scan' ? 'Maximum visited inputs, 1–200000; independent of result offset' :
+            p.name === 'max_bytes' ? 'Maximum searched bytes, 1–16777216' :
+                p.name === 'offset' && p.default !== '-1' ? 'Skip matching result rows; does not continue an incomplete scan' :
+                    p.semantic === 'function_ref' ? 'Function name or explicit address' : p.semantic === 'address' ? 'Explicit hexadecimal address' :
+                        `${flag(p.name)} (${p.type}${p.name === 'limit' ? ', 1–1000' : p.name === 'length' ? ', 1–65536 bytes' : ''})`,
         ...(p.required ? { required: true } : {}), ...(defaultValue === undefined ? {} : { defaultValue }),
         ...(['json', 'object', 'array', 'any'].includes(p.type) ? {} : { parse: (value) => parsed(p, value) }) };
 }