@eyeauras/insight-cli 0.2.3 → 0.3.0

package/dist/src/runtime-selection.js

@@ -1,8 +1,8 @@
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { join, isAbsolute, resolve } from 'node:path';
-import { fail, object } from './model.js';
+import { fail, object, digest } from './model.js';
 export const runtimeRoot = (directory) => join(directory, 'runtime');
-export function runtimeSelection(directory) {
+export function runtimeSelection(directory, analysis = directory) {
     const path = join(runtimeRoot(directory), 'selection.json');
     if (!existsSync(path))
         return;
@@ -15,23 +15,30 @@ export function runtimeSelection(directory) {
             fail('binding', 'Managed runtime moved outside its owned installation.');
         // Workspace resolves AppData physically; older install receipts can retain a profile
         // alias such as /tmp -> /private/tmp. Accept that same profile, never an inner escape.
-        let profile, recorded, home;
+        let profile, recorded, owned, home, retained = false;
         try {
             profile = realpathSync.native(directory);
             recorded = realpathSync.native(recordedProfile);
+            owned = realpathSync.native(analysis);
+            if (recorded !== profile && recorded !== owned) {
+                const marker = object(JSON.parse(readFileSync(join(recorded, '.insight-analysis.json'), 'utf8')));
+                retained = marker.schema === 1 && marker.binding === digest(profile);
+            }
+            if (realpathSync.native(runtimeRoot(directory)) !== join(owned, 'runtime') || realpathSync.native(runtimeRoot(recordedProfile)) !== join(owned, 'runtime'))
+                fail('binding', 'Managed runtime root differs from its configured analysis owner.');
             if (existsSync(value.ghidraHome))
                 home = realpathSync.native(value.ghidraHome);
         }
         catch {
             fail('binding', 'Managed runtime profile ownership could not be verified.');
         }
-        if (recorded !== profile || home !== undefined && home !== join(runtimeRoot(profile), 'installations', id, 'ghidra'))
+        if (recorded !== profile && recorded !== owned && !retained || home !== undefined && home !== join(runtimeRoot(owned), 'installations', id, 'ghidra'))
             fail('binding', 'Managed runtime moved outside its owned installation.');
     }
     return value;
 }
-export function runtimeValues(directory, values) {
-    const selected = runtimeSelection(directory);
+export function runtimeValues(directory, values, analysis) {
+    const selected = runtimeSelection(directory, analysis);
     if (!selected)
         return values;
     if (selected.uninstalledAt)

package/dist/src/saved-materials.js

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, opendir, realpath, rename, rm } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { analysisDirectory } from './analysis-storage.js';
 const maximumEntries = 100_000, maximumDepth = 128;
 function fail(code, message) { throw new CliError(message, { code: 'artifacts.' + code }); }
 function check(signal) { if (signal?.aborted)
@@ -190,7 +191,7 @@ export function artifactsCommands() {
             command('save <path>', 'Save a complete independent copy of a file or directory in this profile', ({ args }, context) => {
                 if (typeof args.path !== 'string' || !args.path || args.path.includes('\0'))
                     fail('invalid', 'Provide one file or directory path.');
-                return saveMaterials(context.appArguments.AppDataDirectory, resolve(context.cwd, args.path), context.signal);
+                return saveMaterials(analysisDirectory(context), resolve(context.cwd, args.path), context.signal);
             }, { permission: Permission.Update }),
         ])];
 }

package/dist/src/tool-runtime/installer.js

@@ -1,4 +1,5 @@
-import { mkdir, stat, rm, readdir, writeFile, readFile } from 'node:fs/promises';
+import { analysisDirectory } from '../analysis-storage.js';
+import { mkdir, stat, rm, readdir, writeFile, readFile, realpath } from 'node:fs/promises';
 import { join, resolve, sep, dirname } from 'node:path';
 import { cacheArtifact, consumeArchive, extractArchive, fileSha256, archiveName } from './archives.js';
 import { atomicWrite, readJson, toolRoot, withToolLock, installationStage, removeInstallation, treeFingerprint, assertUnused, withToolUse } from './store.js';
@@ -7,7 +8,7 @@ import { digest, fail, text } from '../model.js';
 /** Read-only verification used by an owned child after the command owner has staged a runtime. */
 export async function verifyManagedInstallation(directory, tool, selected) {
     const root = join(toolRoot(directory, tool), 'installations', selected.id);
-    if (selected.schema !== 1 || selected.tool !== tool || selected.mode !== 'managed' || selected.uninstalledAt || !/^[a-f0-9]{64}$/.test(selected.id) || selected.root !== root || !resolve(selected.executable).startsWith(resolve(root) + sep))
+    if (selected.schema !== 1 || selected.tool !== tool || selected.mode !== 'managed' || selected.uninstalledAt || !/^[a-f0-9]{64}$/.test(selected.id) || await realpath(selected.root) !== await realpath(root) || !(await realpath(selected.executable)).startsWith(await realpath(root) + sep))
         fail('binding', 'Invalid managed tool installation receipt.');
     const ready = await readJson(join(root, 'ready.json'));
     const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
@@ -27,8 +28,8 @@ export class ToolInstaller {
         this.c = c;
         this.descriptor = descriptor;
         this.directory = c.appArguments.AppDataDirectory;
-        this.root = toolRoot(this.directory, descriptor.id);
-        this.cache = join(this.directory, 'runtime/cache');
+        this.root = toolRoot(analysisDirectory(c), descriptor.id);
+        this.cache = join(analysisDirectory(c), 'runtime/cache');
     }
     async receipt() { return readJson(join(this.root, 'selection.json')); }
     async status() {
@@ -105,7 +106,7 @@ export class ToolInstaller {
         if (selected.schema !== 1 || selected.tool !== this.descriptor.id || !/^[a-f0-9]{64}$/.test(selected.id))
             fail('binding', 'Invalid tool installation receipt.');
         const root = join(this.root, 'installations', selected.id);
-        if (selected.root !== root || selected.mode === 'managed' && !resolve(selected.executable).startsWith(resolve(root) + sep))
+        if (await realpath(selected.root) !== await realpath(root) || selected.mode === 'managed' && !(await realpath(selected.executable)).startsWith(await realpath(root) + sep))
             fail('binding', 'Selected tool points outside its owned installation.');
         const ready = await readJson(join(root, 'ready.json'));
         const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
@@ -131,7 +132,7 @@ export class ToolInstaller {
             await verifyManagedInstallation(this.directory, this.descriptor.id, selected);
         else if (await fileSha256(selected.executable, this.c.signal) !== selected.fingerprint)
             fail('binding', 'Selected tool code differs from its verified installation.');
-        if (selected.execution && (!resolve(selected.execution.executable).startsWith(resolve(root) + sep) || await treeFingerprint(root) !== selected.executionFingerprint))
+        if (selected.execution && (!(await realpath(selected.execution.executable)).startsWith(await realpath(root) + sep) || await treeFingerprint(root) !== selected.executionFingerprint))
             fail('binding', 'Owned external-tool execution copy differs from its verified installation.');
         if (selected.mode === 'external' && this.descriptor.externalInputs && (!selected.externalInputs || digest(await this.descriptor.externalInputs(selected.executable, this.c)) !== digest(selected.externalInputs)))
             fail('binding', 'External tool family differs from its verified installation.');

package/dist/src/tool-runtime/launch-worker.js

@@ -19,7 +19,9 @@ async function main() {
         if (input.length > 4 * 1024 ** 2)
             throw Error('Launch input exceeds its bound');
     }
-    if (await realpath(String(record.root)) !== join(root, 'runtime/runs', id))
+    // Factory's stable profile remains local while the complete runtime tree can be
+    // an authorized analysis-storage alias. Child paths must still stay inside it.
+    if (await realpath(String(record.root)) !== join(await realpath(join(root, 'runtime')), 'runs', id))
         throw Error('Launch storage changed');
     const plan = JSON.parse(input);
     if (plan.executable !== record.executable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
   "main": "./dist/src/index.js",
@@ -24,7 +24,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@eyeauras/cli-factory": "https://raw.githubusercontent.com/iXab3r/insight-cli/73459aecc88da6f878988b64f71ab72b34a83c45/vendor/factory-core-74e7a64.tgz",
+    "@eyeauras/cli-factory": "https://raw.githubusercontent.com/iXab3r/insight-cli/b0d2805ef97face11ab131e8aa39b34216eefaf0/vendor/factory-core-0413409.tgz",
     "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/f47f6d14e8aadc6b6778a6e3627bbb08909521d2/vendor/factory-ipc-7c403d8.tgz",
     "@modelcontextprotocol/sdk": "1.32.1",
     "tar": "7.5.22",

package/references/artifacts.md

@@ -1,7 +1,7 @@
 # Save ordinary research materials
 
 `insight-cli artifacts save <path> --json` saves a file or a settled directory tree in
-the selected profile's AppData. It needs Factory Update permission and does not require
+the selected profile's [analysis storage](storage.md), which defaults to AppData. It needs Factory Update permission and does not require
 Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
 paths resolve against the caller's working directory. Use `--help` for generated syntax.
 

package/references/managed-runtime.md

@@ -79,7 +79,7 @@ operations until `connect`/`start`. `server connect/disconnect` retain their con
 An external server remains configured through profile server/repository/account fields and Factory
 secrets; `server stop` cannot stop that external service.
 
-Code/cache/installation receipts live under profile AppData `runtime/`; research remains under
+Code/cache/installation receipts live under configured [analysis storage](storage.md) `runtime/`; research remains under
 `workspace/`, and saved files under `materials/`. One selected immutable installation serves many
 isolated JVM contexts; each has its own projects, home, settings, cache/temp and authenticated
 endpoint. No per-agent copy of the Ghidra code distribution is required. This is process and data

package/references/native/InsightResearchQueries.java

@@ -172,14 +172,45 @@ public class InsightResearchQueries extends GhidraScript {
   }
 
   byte[] patternMasks;
-  Object execute(String operation)throws Exception{return switch(operation){case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
+  Object decodeInstructions()throws Exception{
+    Address start=address(str("address",""));int maximum=number("max_bytes",64,1,4096),maxInstructions=number("max_instructions",16,1,256);
+    String language=currentProgram.getLanguageID().toString();
+    // Other processors may require mode propagation or delay-slot handling. Fail explicitly
+    // until those semantics have their own native acceptance; never fall back to an Update API.
+    if(!currentProgram.getLanguage().getProcessor().toString().equalsIgnoreCase("x86"))throw new UnsupportedOperationException("Read-only decode currently supports x86 languages only; language/context unavailable: "+language);
+    MemoryBlock block=currentProgram.getMemory().getBlock(start);
+    if(block==null||!block.isInitialized()||!block.isExecute())throw new IllegalArgumentException("Decode requires initialized executable memory");
+    int available=(int)Math.min(maximum,block.getEnd().subtract(start)+1);byte[] input=new byte[available];
+    if(currentProgram.getMemory().getBytes(start,input)!=available)throw new IllegalStateException("Incomplete executable memory read");
+    var decoder=new ghidra.app.util.PseudoDisassembler(currentProgram);List<Object> rows=new ArrayList<>();int consumed=0;String reason="byte_limit";
+    while(consumed<input.length&&rows.size()<maxInstructions){
+      boundedMonitor.checkCancelled();Address at=start.addNoWrap(consumed);ghidra.app.util.PseudoInstruction instruction;
+      try{instruction=decoder.disassemble(at,Arrays.copyOfRange(input,consumed,input.length));}
+      catch(ghidra.program.model.lang.InsufficientBytesException error){reason="truncated_instruction";break;}
+      catch(ghidra.program.model.lang.UnknownInstructionException error){reason="undecodable";break;}
+      catch(ghidra.program.model.lang.UnknownContextException error){reason="context_unavailable";break;}
+      if(instruction==null){reason="undecodable";break;}
+      int length=instruction.getLength();if(length<1||length>input.length-consumed){reason="truncated_instruction";break;}
+      List<String> operands=new ArrayList<>();for(int i=0;i<instruction.getNumOperands();i++)operands.add(instruction.getDefaultOperandRepresentation(i));
+      var flow=instruction.getFlowType();List<String> targets=new ArrayList<>();
+      if(!flow.isComputed())for(Address target:instruction.getFlows())if(target!=null&&!target.equals(Address.NO_ADDRESS))targets.add(target.toString());
+      rows.add(map("address",at.toString(),"bytes",HexFormat.of().formatHex(Arrays.copyOfRange(input,consumed,consumed+length)),"length",length,"mnemonic",instruction.getMnemonicString(),"operands",operands,"direct_targets",targets,"flow",flow.toString(),"computed_flow",flow.isComputed()));
+      consumed+=length;
+      if(flow.isTerminal()){reason="terminal_flow";break;}
+      if(flow.isJump()&&!flow.isConditional()){reason="control_flow";break;}
+    }
+    if(consumed<input.length&&rows.size()==maxInstructions&&reason.equals("byte_limit"))reason="instruction_limit";
+    if(consumed==input.length&&available<maximum&&reason.equals("byte_limit"))reason="executable_block_end";
+    return map("address",start.toString(),"language",language,"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString(),"input_bytes",HexFormat.of().formatHex(input),"input_sha256",HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(input)),"maximum_bytes",maximum,"maximum_instructions",maxInstructions,"instructions",rows,"consumed_bytes",consumed,"stop_reason",reason,"truncated",List.of("byte_limit","instruction_limit","truncated_instruction","executable_block_end").contains(reason),"semantics","Linear pseudo instructions in the selected program context; direct targets are computed from bytes, not function membership or stored xrefs.");
+  }
+  Object execute(String operation)throws Exception{return switch(operation){case "/research_view"->map("modification",Long.toString(currentProgram.getModificationNumber()),"language",currentProgram.getLanguageID().toString(),"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString());case "/decode_instructions"->decodeInstructions();case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
   public void run()throws Exception{
     var request=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();p=request.getAsJsonObject("parameters");maxScan=number("max_scan",100000,1,200000);limit=number("limit",100,1,1000);offset=number("offset",0,0,2000000);deadline=System.nanoTime()+number("timeout_seconds",5,1,30)*1000000000L;
     boundedMonitor=TimeoutTaskMonitor.timeoutIn(number("timeout_seconds",5,1,30),TimeUnit.SECONDS,monitor);
     Map<String,Object> result;long modification=currentProgram.getModificationNumber();try{
       Object value=execute(request.get("operation").getAsString());
       if(currentProgram.getModificationNumber()!=modification)throw new IllegalStateException("Read-only query changed the program modification counter");
-      if(value instanceof Map<?,?>)((Map<String,Object>)value).put("read_only",map("modification_unchanged",true));result=map("value",value);
+      if(value instanceof Map<?,?>)((Map<String,Object>)value).put("read_only",map("modification_unchanged",true,"modification",Long.toString(modification)));result=map("value",value);
     }catch(Exception error){result=map("error",map("code",error instanceof UnsupportedOperationException?"unsupported":error instanceof IllegalArgumentException?"invalid":"partial","message",Objects.toString(error.getMessage(),"Native query failed")));}
     finally{boundedMonitor.finished();if(temporaryTypes!=null){temporaryTypes.endTransaction(temporaryTransaction,false);temporaryTypes.close();}}
 

package/references/research.md

@@ -99,3 +99,43 @@ publish program work. Switching modes retains private edits and other sessions k
 
 Selected native SDK commands and their effect/budget contracts are described in
 [native workflows](native-workflows.md).
+
+`functions get/decompile` failures include `selector`, stable `reason` and, when supplied by
+native, a sanitized diagnostic of at most 500 Unicode characters. Reasons distinguish
+`function_not_found`, `native_function_failure`, `selector_mismatch`, `invalid_native_shape`,
+`missing_signature` and `missing_decompiler_text`. Missing definitions remain failures; reads
+never create functions or run analysis. JSON-RPC `cli.execute` preserves the same error data.
+
+The existing `functions inspect` accepts 1–20 distinct names/addresses. Existing `--fields`
+remain valid; unknown fields fail before dispatch. Decompiled text uses per-item
+`--offset-chars` (default 0), `--limit-chars` (default 16000, maximum 32768), and a shared
+`--total-chars` budget (default 64000, maximum 128000), allocated in selector order.
+Each item retains success/not-found/failure and `text` metadata: full returned-native-text
+SHA-256, Unicode code-point length, window, next offset and native truncation. A zero-length
+window can mean the total budget was exhausted. A last CLI page does not establish native
+completeness. Use fewer selectors to advance a starved item. The one MiB response cap still
+applies to all fields. These are text/result bounds, not a native decompiler CPU budget.
+
+Keep `value.view.identity` and supply `--expect-view <identity>` on continuation. An observed
+context generation, snapshot or revision change rejects continuation with `changed_view`.
+Hashes bind each observed native text; compare them across pages as well. A view identity is
+conservative across lifecycle changes and does not assert determinism of the decompiler.
+
+For compact evidence, use `--save-owner-directory <absolute-new-path>`. The elected CLI owner
+writes full returned native text (at most four MiB per function, at most 20 functions) to numbered
+hash-named `.c` files and writes `manifest.json` last. The response omits inline code and gives
+absolute paths, coverage, hashes, lengths and native truncation. This directory is on the owner
+host, including through JSON-RPC; it is never silently a client-host path. An existing directory
+is rejected. A filesystem failure can leave a partial new directory without a completed manifest;
+retain it for inspection and choose a fresh directory for another explicit save.
+
+`functions decode --address <address> --max-bytes 64 --max-instructions 16` uses Ghidra pseudo
+instructions without defining listing instructions, functions or xrefs, running analyzers or
+saving state. It requires initialized executable memory and currently supports x86 language
+variants; other languages return an explicit unsupported capability error. Bounds are 1–4096
+bytes in one executable block and 1–256 instructions. Results bind input bytes/hash, language,
+compiler and context view to instructions, consumed bytes and stop reason. Direct targets are
+computed from instruction bytes, not proof of function membership or stored xrefs. Indirect
+flow has no invented target. Decoding stops at terminal/unconditional flow, input/instruction
+bounds, undecodable/truncated bytes or unavailable context. Existing `disassemble-bytes` remains
+an Update operation with its original guards.

package/references/setup.md

@@ -1,5 +1,9 @@
 # Setup
 
+Inspect `storage show --json` and read [analysis storage](storage.md) before moving databases.
+Use `storage configure` for an empty profile or `storage migrate` for existing work. Factory
+control metadata and keyring identity stay in their original locations.
+
 Use Node 24+ and `ghidra install` to deliver Ghidra 12.1.2, JDK 21, native components and
 server support. See [managed runtime](managed-runtime.md) for download/install/offline archives,
 external executable paths, status/doctor and safe removal. Existing Factory profile `java` and

package/references/storage.md

@@ -0,0 +1,99 @@
+# Analysis storage and migration
+
+`storage show --json` reports effective profile storage, availability, active file/byte usage,
+exact included trees and retained migration. The default is Factory profile AppData. No
+checkout, environment or automatic disk fallback changes it. The non-secret setting is
+`analysisDirectory` in Factory's profile (`profile show` also displays it). Use storage commands
+to change it safely.
+
+```sh
+insight-cli permissions grant Update
+insight-cli storage show --json
+insight-cli storage configure --directory "/mnt/analysis volume" --json
+```
+
+`configure` requires no existing analysis entries. With existing data use `migrate`.
+The directory is a **base**: the effective root appends `insight-cli/<profile>`, preserving
+profile isolation. Choose an ordinary empty destination profile directory on a mounted local
+filesystem. Spaces and Unicode are supported. Factory restricts the dedicated destination root to the
+current user, including a Windows ACL; a filesystem that cannot apply this protection fails
+before copying.
+
+The complete `workspace`, `materials`, `temp` and `runtime` trees move: immutable inputs,
+artifact/candidate snapshots, workspace SQLite DB/WAL, native private project/context DBs,
+local Ghidra Server repositories, operation/publication/import journals, debugger traces,
+process captures, exports, native helper compilation and verification working data.
+**Runtime installations, acquisition caches, selections and process receipts move too**;
+installation staging and activation must share a filesystem. External tool installations and
+user-selected outputs outside these trees keep their locations.
+
+Factory keeps profiles, permissions, IPC election/socket, migration-control metadata and
+application logs in current-user AppData. Secrets stay in the OS keyring. Credential/profile
+identities do not change. Updating/installing npm never migrates a profile automatically.
+
+## Move an existing profile
+
+Finish changing commands, close native contexts, and stop this profile's owned server/tool
+processes through ordinary CLI commands. Inspect `tools processes --json`. Unverified lifetimes
+also block migration. Do not kill guessed PIDs or stop other profiles to make preflight pass.
+Factory retains IPC ownership and command admission; other profiles can keep working.
+
+```sh
+insight-cli storage migrate --directory "/mnt/analysis volume" --dry-run --json
+insight-cli storage migrate --directory "/mnt/analysis volume" --json
+insight-cli storage show --json
+```
+
+Dry-run checks separation, destination contents, access, conservative capacity and quiescence
+without reserving/copying a migration. Source/destination/configuration roots cannot be equal
+or nested. Destination symlink roots, escaping source links, special files, unresolved links
+and inventories above one million entries or 128 directory levels are rejected. Internal
+links retain their exact target strings. Preflight does not reserve space; concurrent disk use
+can still cause a copy failure.
+
+Migration durably reserves its journal, hashes stable source bytes, streams/syncs the copy,
+independently hashes destination bytes and rechecks the source. Only then does it replace source
+trees with permanent compatibility links and commit the Factory setting. Original trees are
+renamed into `.storage-retained/<migration>` on their original volume. Copy/activation never
+deletes them, including on failures. Existing IDs, requests, journals, candidate snapshots and
+receipts retain exact bytes. Compatibility paths preserve old absolute references: do not remove
+those links or their profile/source ancestors manually after migrating.
+
+## Interruptions, uncertainty and retention
+
+```sh
+insight-cli storage resume --json
+insight-cli storage rollback --json
+```
+
+Ordinary research freezes during incomplete copy/activation/rollback/cleanup. `show` and Factory
+profile inspection remain available. Resume verifies completed files, recopies an incomplete
+file, rechecks capacity and finishes the retained transaction. Source and destination filesystem
+anchor identities are bound durably. Missing/replaced volumes fail without creating a system-disk
+fallback; mount the original volume before resuming.
+
+Rollback restores retained source and the prior Factory setting. After activation it requires
+an unchanged destination and a verified retained source. Native reopening or later findings can
+make rollback unsafe, in which case it refuses and preserves both copies. Use forward migration
+to another empty base after using the new location. A rolled-back destination remains for manual
+inspection/removal and is never automatically adopted. Cleanup permanently disables rollback.
+
+Unknown script/publication effects do **not** need abandonment before migrating a stopped
+profile. Migration starts no worker, replays no script/check-in and marks no unknown outcome
+applied. Inspect the original request after migrating; existing [recovery](recovery.md)
+restrictions and independent readback requirements still apply.
+
+After independent native reopen and saved-file readback, free retained source explicitly:
+
+```sh
+insight-cli permissions grant Destructive
+insight-cli storage cleanup --json
+```
+
+Cleanup verifies retained bytes, records irreversible intent, then deletes only that owned
+backup. Interrupted cleanup continues through `storage resume`; rollback is already disabled.
+Compatibility links, receipts and manifests remain. Clean or roll back the current migration
+before starting another. This release provides no nonempty-destination adoption, reverse
+synchronization, live-DB snapshotting or network-filesystem guarantees. POSIX directory fsync
+is used. Windows has file fsync and rename/junction semantics; Node cannot fsync directories
+there, and internal symlinks can require OS privileges.

package/runtime/toolbox.json

@@ -6,7 +6,9 @@
       "title": "insight-cli",
       "path": "SKILL.md",
       "resources": {
-        "references/agent-execution.md": "references/agent-execution.md"
+        "references/agent-execution.md": "references/agent-execution.md",
+        "references/storage.md": "references/storage.md",
+        "references/recovery.md": "references/recovery.md"
       }
     },
     {
@@ -16,7 +18,8 @@
       "resources": {
         "references/recovery.md": "references/recovery.md",
         "references/artifacts.md": "references/artifacts.md",
-        "references/agent-execution.md": "references/agent-execution.md"
+        "references/agent-execution.md": "references/agent-execution.md",
+        "references/storage.md": "references/storage.md"
       }
     },
     {
@@ -35,7 +38,8 @@
         "references/archive.md": "references/archive.md",
         "references/extensions-and-sync.md": "references/extensions-and-sync.md",
         "references/artifacts.md": "references/artifacts.md",
-        "references/agent-execution.md": "references/agent-execution.md"
+        "references/agent-execution.md": "references/agent-execution.md",
+        "references/storage.md": "references/storage.md"
       }
     },
     {
@@ -53,7 +57,9 @@
       "path": "skills/insight-artifacts/SKILL.md",
       "resources": {
         "references/artifacts.md": "references/artifacts.md",
-        "references/agent-execution.md": "references/agent-execution.md"
+        "references/agent-execution.md": "references/agent-execution.md",
+        "references/storage.md": "references/storage.md",
+        "references/recovery.md": "references/recovery.md"
       }
     },
     {

package/skill-bundle/insight-artifacts/SKILL.md

@@ -3,7 +3,7 @@ name: insight-artifacts
 description: Retain a completed reverse-engineering evidence file or directory as an ordinary checkpoint using insight-cli artifacts save. Use after Ghidra or any external tool; preserve existing project formats and source of truth.
 ---
 
-# Insight Artifacts 0.2.3
+# Insight Artifacts 0.3.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

package/skill-bundle/insight-artifacts/references/artifacts.md

@@ -1,7 +1,7 @@
 # Save ordinary research materials
 
 `insight-cli artifacts save <path> --json` saves a file or a settled directory tree in
-the selected profile's AppData. It needs Factory Update permission and does not require
+the selected profile's [analysis storage](storage.md), which defaults to AppData. It needs Factory Update permission and does not require
 Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
 paths resolve against the caller's working directory. Use `--help` for generated syntax.
 

package/skill-bundle/insight-artifacts/references/recovery.md

@@ -0,0 +1,79 @@
+# Continue saved work
+
+Retain the session/target returned by initial open. Continue the tuple through
+`insight-cli ghidra open --session <id> --target <id> --json`. Saved private snapshots and
+pending scalar comparisons persist independently of a backend process. Reopening preserves
+private work; it does not silently receive a newer shared version.
+
+First-import recovery uses the same scoped `ghidra open` or the original request ID/input.
+Import/analysis writes a private snapshot and completion receipt before any initial publication.
+If its worker is still running, continuation reports busy; wait and continue the same scope.
+If that worker stopped before completing its receipt, continuation can repeat private analysis
+from the immutable input while retaining previous attempts. A completed snapshot is reused.
+Initial publication first creates a uniquely named staging object. A separate read-only process
+verifies its complete saved DB buffers before a conditional server move to the absent canonical
+path. It never checks in a new version of an existing canonical item. Lost promotion replies
+are reconciled against the retained identity, one-version history and complete saved buffers.
+Interrupted staging objects remain retained and can be replaced by another private stage;
+they are not adopted as the canonical model. Foreign or mismatched canonical state stays blocked.
+An older direct create that is provably owned and left only an incomplete `<Recovered>` entry
+can be moved aside without deletion; its bytes and original receipt remain preserved.
+
+Legacy first-import failures are also recoverable in the original profile. Continuation first
+establishes that the old owned bootstrap worker has ended, then uses an authoritative repository
+probe. An absent canonical item permits private preparation; an existing first version requires
+independent readback. The old project, intent and original session/target remain preserved.
+
+If a response was lost, inspect `sessions status <session> --target <target>`. Never infer
+`applied` from a connection failure. A changing command's optional request ID binds one effective
+intent inside the profile. Repeating the same ID/input retrieves its recorded outcome or
+unresolved state; changing input under that ID fails. Without an ID, calls are new intentions.
+
+An unknown or partial effect retains its request intent, snapshots and native stage. Open the
+same tuple to reconcile supported outcomes. A committed merge is verified against its recorded
+server version and complete saved buffers through independent read authority; it is never
+checked in again merely because its response was lost. Until verification succeeds, publication
+for this shared target is blocked across sessions. Saved private work remains retained.
+
+Scalar reconciliation observes and saves an already present effect; it does not execute the
+setter again. Supported structural/function edits retain a candidate snapshot after an incomplete
+response; continuation can verify every requested effect in that immutable snapshot and adopt it
+without replay. If the complete result cannot be established, the candidate and previous saved
+private view remain retained. An unproved program/script/external outcome remains unresolved. Preserve the profile
+storage and credential store. Do not delete another session's project, stop a process by guessed
+PID/port, or blindly repeat a script/external action to turn uncertainty into success.
+
+The older prototype's `workers`, `findings`, `integrate` and batch `recover` commands are not the
+public facade API. Its coordinator journals remain separate and are never silently migrated.
+
+A lost UI navigation response can be verified from the live authenticated cursor without another
+goto. If its original owned GUI process has exited, continuation reports the uncertain UI action
+as disconnected and retains saved program work. It does not recreate the old cursor or re-enable
+a previous prompt policy. Other unproved live UI effects remain retained until their outcome is
+established or the original process is known to have ended.
+
+## Abandon an uncertain private program attempt
+
+A post-mutation save timeout does not repeat the script or issue another save in the
+error handler. Status exposes the original request identity and retained phase/budget.
+Arbitrary script effects are never inferred from metadata or from an unverified DB.
+After inspecting the retained attempt, explicitly stop only its verified owned worker
+(`tools processes`, then `tools processes kill <process>` if required). Resume the
+last acknowledged private snapshot with:
+
+```sh
+insight-cli permissions grant Destructive
+insight-cli ghidra abandon --session <session> --target <target> \
+  --request-id <original-request> --acknowledge-unknown-effects --json
+insight-cli ghidra open --session <session> --target <target> --json
+```
+
+Abandon requires exactly one unresolved private program operation, an unchanged verified
+previous snapshot/generation, a stopped original worker and no active publication or live
+debugger. It retains the native project, candidate artifacts, original intent/execution and
+previous diagnostic result. Its terminal request is `failed` / `state: abandoned` with
+`outcome: unknown`; no effect is marked applied. Repeating abandonment retrieves the same
+result. Earlier saved private edits remain pending. The original changing request ID cannot
+execute again. Abandoning never undoes external effects or establishes what an arbitrary
+script did; the acknowledgement explicitly accepts that uncertainty. Publication recovery,
+initial import, UI and debugger attempts use their own protocols and cannot use this command.

package/skill-bundle/insight-artifacts/references/storage.md

@@ -0,0 +1,99 @@
+# Analysis storage and migration
+
+`storage show --json` reports effective profile storage, availability, active file/byte usage,
+exact included trees and retained migration. The default is Factory profile AppData. No
+checkout, environment or automatic disk fallback changes it. The non-secret setting is
+`analysisDirectory` in Factory's profile (`profile show` also displays it). Use storage commands
+to change it safely.
+
+```sh
+insight-cli permissions grant Update
+insight-cli storage show --json
+insight-cli storage configure --directory "/mnt/analysis volume" --json
+```
+
+`configure` requires no existing analysis entries. With existing data use `migrate`.
+The directory is a **base**: the effective root appends `insight-cli/<profile>`, preserving
+profile isolation. Choose an ordinary empty destination profile directory on a mounted local
+filesystem. Spaces and Unicode are supported. Factory restricts the dedicated destination root to the
+current user, including a Windows ACL; a filesystem that cannot apply this protection fails
+before copying.
+
+The complete `workspace`, `materials`, `temp` and `runtime` trees move: immutable inputs,
+artifact/candidate snapshots, workspace SQLite DB/WAL, native private project/context DBs,
+local Ghidra Server repositories, operation/publication/import journals, debugger traces,
+process captures, exports, native helper compilation and verification working data.
+**Runtime installations, acquisition caches, selections and process receipts move too**;
+installation staging and activation must share a filesystem. External tool installations and
+user-selected outputs outside these trees keep their locations.
+
+Factory keeps profiles, permissions, IPC election/socket, migration-control metadata and
+application logs in current-user AppData. Secrets stay in the OS keyring. Credential/profile
+identities do not change. Updating/installing npm never migrates a profile automatically.
+
+## Move an existing profile
+
+Finish changing commands, close native contexts, and stop this profile's owned server/tool
+processes through ordinary CLI commands. Inspect `tools processes --json`. Unverified lifetimes
+also block migration. Do not kill guessed PIDs or stop other profiles to make preflight pass.
+Factory retains IPC ownership and command admission; other profiles can keep working.
+
+```sh
+insight-cli storage migrate --directory "/mnt/analysis volume" --dry-run --json
+insight-cli storage migrate --directory "/mnt/analysis volume" --json
+insight-cli storage show --json
+```
+
+Dry-run checks separation, destination contents, access, conservative capacity and quiescence
+without reserving/copying a migration. Source/destination/configuration roots cannot be equal
+or nested. Destination symlink roots, escaping source links, special files, unresolved links
+and inventories above one million entries or 128 directory levels are rejected. Internal
+links retain their exact target strings. Preflight does not reserve space; concurrent disk use
+can still cause a copy failure.
+
+Migration durably reserves its journal, hashes stable source bytes, streams/syncs the copy,
+independently hashes destination bytes and rechecks the source. Only then does it replace source
+trees with permanent compatibility links and commit the Factory setting. Original trees are
+renamed into `.storage-retained/<migration>` on their original volume. Copy/activation never
+deletes them, including on failures. Existing IDs, requests, journals, candidate snapshots and
+receipts retain exact bytes. Compatibility paths preserve old absolute references: do not remove
+those links or their profile/source ancestors manually after migrating.
+
+## Interruptions, uncertainty and retention
+
+```sh
+insight-cli storage resume --json
+insight-cli storage rollback --json
+```
+
+Ordinary research freezes during incomplete copy/activation/rollback/cleanup. `show` and Factory
+profile inspection remain available. Resume verifies completed files, recopies an incomplete
+file, rechecks capacity and finishes the retained transaction. Source and destination filesystem
+anchor identities are bound durably. Missing/replaced volumes fail without creating a system-disk
+fallback; mount the original volume before resuming.
+
+Rollback restores retained source and the prior Factory setting. After activation it requires
+an unchanged destination and a verified retained source. Native reopening or later findings can
+make rollback unsafe, in which case it refuses and preserves both copies. Use forward migration
+to another empty base after using the new location. A rolled-back destination remains for manual
+inspection/removal and is never automatically adopted. Cleanup permanently disables rollback.
+
+Unknown script/publication effects do **not** need abandonment before migrating a stopped
+profile. Migration starts no worker, replays no script/check-in and marks no unknown outcome
+applied. Inspect the original request after migrating; existing [recovery](recovery.md)
+restrictions and independent readback requirements still apply.
+
+After independent native reopen and saved-file readback, free retained source explicitly:
+
+```sh
+insight-cli permissions grant Destructive
+insight-cli storage cleanup --json
+```
+
+Cleanup verifies retained bytes, records irreversible intent, then deletes only that owned
+backup. Interrupted cleanup continues through `storage resume`; rollback is already disabled.
+Compatibility links, receipts and manifests remain. Clean or roll back the current migration
+before starting another. This release provides no nonempty-destination adoption, reverse
+synchronization, live-DB snapshotting or network-filesystem guarantees. POSIX directory fsync
+is used. Windows has file fsync and rename/junction semantics; Node cannot fsync directories
+there, and internal symlinks can require OS privileges.

package/skill-bundle/insight-binary/SKILL.md

@@ -3,7 +3,7 @@ name: insight-binary
 description: Query structured PE, ELF and thin Mach-O headers, sections, imports and exports, or make an explicitly guarded new PE subsystem copy through insight-cli binary. Use for scoped binary structure, linkage and copy-only header edits without target execution.
 ---
 
-# Insight Binary 0.2.3
+# Insight Binary 0.3.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