@eyeauras/insight-cli 0.2.4 → 0.3.1

package/references/native/InsightImportProgress.java

@@ -0,0 +1,42 @@
+import com.google.gson.*;
+import ghidra.util.task.TaskMonitorAdapter;
+import insight.InsightInitialJournal;
+import java.nio.file.*;
+import java.time.Instant;
+import java.util.*;
+
+/** A bounded observation channel, never a completion receipt or an overall percentage. */
+class InsightImportProgress extends TaskMonitorAdapter implements AutoCloseable {
+    private final Path root;
+    private final String target,started=Instant.now().toString();
+    private final Timer heartbeat=new Timer("insight-import-progress",true);
+    private String phase="starting",state="running";
+    private String message="";
+    private long completed,total;
+    private boolean indeterminate=true;
+    private volatile Throwable writeFailure;
+    InsightImportProgress(Path root,String target)throws Exception{
+        super(true);this.root=root;this.target=target;emit();
+        heartbeat.scheduleAtFixedRate(new TimerTask(){public void run(){try{emit();}catch(Throwable failure){writeFailure=failure;}}},2000,2000);
+    }
+    synchronized void phase(String value)throws Exception{phase=value;setMessage("");initialize(0);setIndeterminate(true);emit();}
+    public synchronized void setMessage(String value){message=Objects.toString(value,"");}
+    public synchronized String getMessage(){return message;}
+    public synchronized void initialize(long maximum){completed=0;total=maximum;indeterminate=maximum<=0;}
+    public synchronized void setProgress(long value){completed=value;}
+    public synchronized void incrementProgress(long value){completed+=value;}
+    public synchronized long getProgress(){return completed;}
+    public synchronized void setMaximum(long value){total=value;}
+    public synchronized long getMaximum(){return total;}
+    public synchronized void setIndeterminate(boolean value){indeterminate=value;}
+    public synchronized boolean isIndeterminate(){return indeterminate;}
+    synchronized void state(String value)throws Exception{state=value;emit();}
+    private synchronized void emit()throws Exception{
+        JsonObject p=new JsonObject();p.addProperty("schema",1);p.addProperty("target",target);p.addProperty("phase",phase);p.addProperty("state",state);
+        p.addProperty("pid",ProcessHandle.current().pid());p.addProperty("startedAt",started);p.addProperty("updatedAt",Instant.now().toString());
+        p.addProperty("indeterminate",isIndeterminate());String message=Objects.toString(getMessage(),"");p.addProperty("message",message.substring(0,Math.min(message.length(),1024)));
+        if(!isIndeterminate()&&getMaximum()>0){p.addProperty("completed",getProgress());p.addProperty("total",getMaximum());}
+        InsightInitialJournal.write(root.resolve("progress.json"),p);
+    }
+    public synchronized void close()throws Exception{heartbeat.cancel();if(state.equals("running"))state=isCancelled()?"cancelled":"failed";emit();if(writeFailure!=null)throw new java.io.IOException("Progress persistence failed",writeFailure);}
+}

package/references/native/InsightInitialImport.java

@@ -23,6 +23,8 @@ class InsightInitialImport {
                 JsonObject s=new JsonObject();s.addProperty("intentHash",InsightInitialJournal.hash(root.resolve("intent.json")));
                 s.addProperty("phase","importing");s.addProperty("pid",ProcessHandle.current().pid());s.addProperty("snapshot","attempt-"+UUID.randomUUID()+".gzf");
                 Path attempt=root.resolve(InsightInitialJournal.text(s,"snapshot")+".json");InsightInitialJournal.write(attempt,s);InsightInitialJournal.write(journal,s);
+                try(var progress=new InsightImportProgress(root,InsightInitialJournal.text(p,"target"))){
+                progress.phase("runtime-initialization");
                 Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
                 JsonObject settings=p.getAsJsonObject("settings"),request=new JsonObject();
                 request.addProperty("input",input.toString());request.addProperty("output",root.resolve(InsightInitialJournal.text(s,"snapshot")).toString());
@@ -31,10 +33,14 @@ class InsightInitialImport {
                 if(settings.has("compilerSpec"))request.add("compiler_spec",settings.get("compilerSpec"));
                 if(settings.has("imageBase"))request.add("image_base",settings.get("imageBase"));
                 if(settings.has("loaderOptions"))request.add("options",settings.get("loaderOptions"));
-                JsonObject metadata=new Gson().toJsonTree(InsightSdkFiles.importProgram(request)).getAsJsonObject();
+                JsonObject metadata;
+                try{metadata=new Gson().toJsonTree(InsightSdkFiles.importProgram(request,progress)).getAsJsonObject();}
+                catch(Throwable failure){progress.state(progress.isCancelled()?"cancelled":"failed");throw failure;}
+                progress.phase("snapshot-verification");
                 Path file=root.resolve(InsightInitialJournal.text(s,"snapshot"));InsightInitialJournal.sync(file);
                 s.add("metadata",metadata);s.addProperty("snapshotSha256",InsightInitialJournal.hash(file));s.addProperty("phase","prepared");InsightInitialJournal.write(attempt,s);InsightInitialJournal.write(journal,s);
-                InsightInitialJournal.prepared(root);out.println("{\"state\":\"prepared\"}");
+                InsightInitialJournal.prepared(root);progress.state("prepared");out.println("{\"state\":\"prepared\"}");
+                }
             }
             System.exit(0);
         }catch(Throwable failure){failure.printStackTrace(System.err);out.println("{\"state\":\"failed\"}");System.exit(1);}

package/references/native/InsightSdkFiles.java

@@ -54,14 +54,17 @@ class InsightSdkFiles {
             return Map.of("supported",rows,"all_loader_names",LoaderService.getAllLoaderNames());
         }
     }
-    static Object importProgram(JsonObject p) throws Exception {
+    static void phase(TaskMonitor monitor,String phase)throws Exception{if(monitor instanceof InsightImportProgress progress)progress.phase(phase);}
+    static Object importProgram(JsonObject p) throws Exception {return importProgram(p,TaskMonitor.DUMMY);}
+    static Object importProgram(JsonObject p,TaskMonitor monitor) throws Exception {
+        phase(monitor,"import");
         String selected=text(p,"loader");Object consumer=new Object();Loader loader=null;
         if(selected.isEmpty()){
             Language language=text(p,"language").isEmpty()?null:DefaultLanguageService.getLanguageService().getLanguage(new LanguageID(text(p,"language")));
             CompilerSpec compiler=language==null?null:text(p,"compiler_spec").isEmpty()?language.getDefaultCompilerSpec():language.getCompilerSpecByID(new CompilerSpecID(text(p,"compiler_spec")));
-            var loaded=language==null?AutoImporter.importByUsingBestGuess(Path.of(text(p,"input")).toFile(),null,"/",consumer,new MessageLog(),TaskMonitor.DUMMY):
-                AutoImporter.importByLookingForLcs(Path.of(text(p,"input")).toFile(),null,"/",language,compiler,consumer,new MessageLog(),TaskMonitor.DUMMY);
-            try{if(loaded==null||loaded.size()!=1)throw new IllegalArgumentException("Expected one imported program");return saveImport(loaded.getPrimaryDomainObject(),p,"automatic");}
+            var loaded=language==null?AutoImporter.importByUsingBestGuess(Path.of(text(p,"input")).toFile(),null,"/",consumer,new MessageLog(),monitor):
+                AutoImporter.importByLookingForLcs(Path.of(text(p,"input")).toFile(),null,"/",language,compiler,consumer,new MessageLog(),monitor);
+            try{if(loaded==null||loaded.size()!=1)throw new IllegalArgumentException("Expected one imported program");return saveImport(loaded.getPrimaryDomainObject(),p,"automatic",monitor);}
             finally{if(loaded!=null)loaded.release(consumer);}
         }
         for(Loader candidate:ClassSearcher.getInstances(Loader.class))if(candidate.getClass().getName().equals(selected)||candidate.getClass().getSimpleName().equals(selected)||candidate.getName().equals(selected)){
@@ -77,24 +80,24 @@ class InsightSdkFiles {
             Language effectiveLanguage=language;if(effectiveLanguage==null&&selectedSpec.getLanguageCompilerSpec()!=null)effectiveLanguage=DefaultLanguageService.getLanguageService().getLanguage(selectedSpec.getLanguageCompilerSpec().languageID);
             var options=configured(loader.getDefaultOptions(provider,selectedSpec,null,false,false),optionValues(p),effectiveLanguage==null?null:effectiveLanguage.getAddressFactory());
             String error=loader.validateOptions(provider,selectedSpec,options,null);if(error!=null)throw new IllegalArgumentException("Native loader rejected options: "+error);
-            var settings=new Loader.ImporterSettings(provider,"OwnedInput",null,"/",false,selectedSpec,options,consumer,new MessageLog(),TaskMonitor.DUMMY);
+            var settings=new Loader.ImporterSettings(provider,"OwnedInput",null,"/",false,selectedSpec,options,consumer,new MessageLog(),monitor);
             var result=loader.load(settings);
             if(result==null)throw new IllegalStateException("Native loader did not return a program");
             try {
                 if(result.size()!=1||!(result.getPrimaryDomainObject() instanceof Program))throw new IllegalArgumentException("Loader must produce one program per explicit target");
-                return saveImport((Program)result.getPrimaryDomainObject(),p,loader.getClass().getName());
+                return saveImport((Program)result.getPrimaryDomainObject(),p,loader.getClass().getName(),monitor);
             } finally {result.release(consumer);}
         }
     }
-    static Object saveImport(Program program,JsonObject p,String loader)throws Exception{
+    static Object saveImport(Program program,JsonObject p,String loader,TaskMonitor monitor)throws Exception{
         boolean analyze=p.has("auto_analyze")&&p.get("auto_analyze").getAsBoolean();
-        if(analyze){ghidra.app.script.GhidraScriptUtil.acquireBundleHostReference();int tx=program.startTransaction("Initial analysis");boolean success=false;
-            try{AutoAnalysisManager analysis=AutoAnalysisManager.getAnalysisManager(program);analysis.initializeOptions();analysis.reAnalyzeAll(null);analysis.startAnalysis(TaskMonitor.DUMMY);success=true;}
+        if(analyze){phase(monitor,"analysis");ghidra.app.script.GhidraScriptUtil.acquireBundleHostReference();int tx=program.startTransaction("Initial analysis");boolean success=false;
+            try{AutoAnalysisManager analysis=AutoAnalysisManager.getAnalysisManager(program);analysis.initializeOptions();analysis.reAnalyzeAll(null);analysis.startAnalysis(monitor);monitor.checkCancelled();success=true;}
             finally{program.endTransaction(tx,success);ghidra.app.script.GhidraScriptUtil.releaseBundleHostReference();}}
         if(p.has("image_base")){int tx=program.startTransaction("Initial image base");boolean success=false;
             try{program.setImageBase(program.getAddressFactory().getDefaultAddressSpace().getAddress(new BigInteger(text(p,"image_base"),16).longValue()),true);success=true;}
             finally{program.endTransaction(tx,success);}}
-        program.saveToPackedFile(Path.of(text(p,"output")).toFile(),TaskMonitor.DUMMY);
+        phase(monitor,"save");program.saveToPackedFile(Path.of(text(p,"output")).toFile(),monitor);monitor.checkCancelled();
         return Map.of("state","imported","loader",loader,"language",program.getLanguageID().toString(),"base_address",program.getImageBase().toString(),
             "compiler",program.getCompilerSpec().getCompilerSpecID().toString(),"sha256",program.getExecutableSHA256(),"auto_analyzed",analyze);
     }

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
@@ -65,3 +69,30 @@ After an import timeout, wait for the original worker to end, raise its budget a
 the original scope. Incomplete private analysis restarts; a completed receipt is reused.
 A save timeout reports `phase: save`, the effective budget and `saveSeconds`. Inspect
 `sessions status`; a native log or broken response stream cannot prove a saved snapshot.
+
+## Initial import and progress
+
+New targets import **without automatic analysis**. Reuse existing selectors/projects before
+opening another copy; `ghidra open --session <session> --target <target>` preserves its bound
+load settings, including older analysis choices. `--no-analysis` makes the fast choice explicit;
+`--analysis` opts into a full analysis only during the first import of a new target.
+After a fast import, use scoped `ghidra analysis run` to process pending analysis, or
+`ghidra analysis reanalyze` to deliberately queue full reanalysis. These are saved private
+mutations; merge deliberately. For a narrow question prefer bounded function disassembly,
+function creation and decompilation first; inspect help for the exact operation.
+
+For long first opens, `ghidra progress --session <session> --target <target> --json`
+reads retained progress without starting Java or repeating the operation. It reports the
+current stage, elapsed time, heartbeat age and native task message/counters when available;
+those counters belong to the current task, not the whole import. Human output also reports
+progress through Factory; `--json` keeps one final JSON result on stdout and stays quiet.
+If the execution host yields, keep its same running execution and inspect progress every
+5-10 seconds when useful; relay stage changes or meaningful stalls, and do other independent
+work. Do not silently extend waits to minutes or start a second import. Until selectors are
+returned, use the existing `sessions list/status` and `tools processes` inventory to locate the
+reserved scope. A stale heartbeat, dead worker or unknown result is not completion: inspect
+`sessions status` and recovery before continuing. Pre-upgrade workers have no progress record;
+null progress means unavailable, never success. Progress is observational, not a completion receipt. This command tracks first open only;
+its old complete record does not describe later `analysis run`/`reanalyze` operations.
+`operation: initial-model` completes after verified shared-model publication; the private
+session context can still be opening. Inspect `sessions status` for context readiness.

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.4
+# Insight Artifacts 0.3.1
 
 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.4
+# Insight Binary 0.3.1
 
 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-capture/SKILL.md

@@ -3,7 +3,7 @@ name: insight-capture
 description: Capture one explicitly authorized native program run, exact stdout/stderr and declared file snapshots through insight-cli capture, then inspect or compare retained reports without replay. Use for controlled input/output research, preserving original files and interrupted or unknown outcomes.
 ---
 
-# Insight Capture 0.2.4
+# Insight Capture 0.3.1
 
 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-cli/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.2.4
+# insight-cli 0.3.1
 
 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
@@ -36,6 +36,14 @@ multi-agent guidance; `skill insight-ghidra`, `skill insight-ilspy` and
 installing npm binaries does not register them in an agent host. See
 [agent connection](references/agent-setup.md) for current setup and access requirements.
 
+Inspect `storage show --json` before relocating a profile. Use the supported
+[storage workflow](references/storage.md), preserving unknown operations and native folders.
+
+
+New targets import without full auto-analysis; `--analysis` opts in at first import.
+Reuse existing session/target selectors before opening another copy. Read [setup](references/setup.md)
+for explicit later analysis and passive first-open progress (`ghidra progress`).
+
 Use generated help as the syntax authority. Catalog metadata describes shipped capabilities;
 profile runtime readiness comes from the selected tool's `status`. Unavailable profile/IPC
 access means execution readiness is unknown. Preserve work and diagnose access before trying

package/skill-bundle/insight-cli/references/archive.md

@@ -0,0 +1,32 @@
+# Exchange private documentation with an archive
+
+Archive exchange is disabled until the selected Factory profile has an explicit `archiveUrl`.
+Use HTTPS for a remote service; local HTTP is supported for local services. URLs cannot contain
+credentials, query parameters or fragments. An optional bearer token is stored with
+`auth login --role archive --password-stdin`; it is a Factory secret and is never passed to
+Ghidra or the debuggee. `auth logout` clears this token as well as external server credentials.
+
+Use `ghidra archive ingest-function --address <entry>` or `ingest-program`, with the usual
+`--session` and `--target`. Both export the selected private view. `--version-label` supplies
+the archive version; its default is `unknown`. Internal project directories are not used as
+version labels. Bulk selection skips default function names unless `--include-default-named`
+is set; `--limit` bounds visited functions. Zero selects all, subject to the documented bound.
+`--dry-run` validates payloads and returns would-be counts without a network request.
+
+The service contract is `POST <archiveUrl>/v1/doc_archive/upsert` with JSON and an optional
+`Authorization: Bearer ...` header. The payload matches the pinned GhidraMCP builder: binary
+name, explicit version, function address, run/tool identity, name/prototype, calling convention,
+flags, matching hash/shape metadata, tags, named locals and instruction comments when present.
+The binary name is the logical target name. Each successful JSON response must contain a
+boolean `created` and a nonnegative integer `conflicts_enqueued`. Redirects are refused.
+
+Results retain created, updated, conflict, skipped and error counts. Archive conflict counts
+describe the external service's decisions; they do not resolve program merge conflicts.
+Use an optional stable `--request-id` when a response might be lost. A repeated ID returns
+the saved successful result or the retained uncertain outcome, without sending again.
+Each outbound payload identity and the source snapshot are retained before dispatch. Unknown
+external outcomes stay observable and do not block unrelated private research. A new request ID
+expresses another explicit submission; the facade does not assume the service can deduplicate it.
+
+Archive requests do not publish the program or alter another session. Developing or deploying
+the external archive service is outside this package; acceptance uses an owned contract fixture.