opencode-session-port 0.1.3 → 0.1.4

package/README.md

@@ -4,7 +4,7 @@
 
 SessionPort is a local plugin for the OpenCode TUI. It captures the sessions of your current project into a single password-encrypted artifact and restores them in another checkout, worktree, or machine. Artifacts travel with Git or any other channel you choose — SessionPort never runs Git commands itself.
 
-> **Status: experimental pre-release (0.1.3).** SessionPort completed one bounded synthetic checkpoint/restore round trip on Windows with OpenCode v2.0.22. That test used test-only password and project-selector seams and staged source, not the npm tarball. On one real Windows OpenCode v2.0.22 host, a bounded diagnostic observed both commands registered (`commands=yes`) but hidden from the command palette and slash list until the keymap layer opted into global mode; 0.1.2 applies that global-mode registration fix, with focused command-registration tests and the TUI build passing. 0.1.3 additionally enables the commands on macOS and Linux through an explicit platform allowlist (`win32`/`darwin`/`linux`); macOS and Linux have NOT been host-tested, and cross-OS artifact interchange is UNVERIFIED. End-to-end execution from the packed package has not been host-tested. Real modal interactions and loading the packed package in OpenCode have not been verified. The checkpoint format may change; no compatibility, security, or platform-support guarantee is made.
+> **Status: experimental pre-release (0.1.4).** SessionPort completed one bounded synthetic checkpoint/restore round trip on Windows with OpenCode v2.0.22. That test used test-only password and project-selector seams and staged source, not the npm tarball. On one real Windows OpenCode v2.0.22 host, a bounded diagnostic observed both commands registered (`commands=yes`) but hidden from the command palette and slash list until the keymap layer opted into global mode; 0.1.2 applies that global-mode registration fix, with focused command-registration tests and the TUI build passing. 0.1.3 additionally enables the commands on macOS and Linux through an explicit platform allowlist (`win32`/`darwin`/`linux`). 0.1.2 and 0.1.3 are published to npm (0.1.3 latest, per a read-only registry check); 0.1.4 is the current local candidate. 0.1.4 is a diagnostics/copy patch only: a failed checkpoint collection now appends a fixed sanitized reason and the known machine code (`Reason: <fixed reason> (<code>).`) for the 17 current collection codes; unknown codes keep the generic text and raw host/exception text is never shown. Collector behavior is unchanged, and no root cause is established for an earlier Windows collection failure; a user later reported a local checkpoint succeeding from the repository checkout, which is not attributed to this patch. macOS has one user-reported successful checkpoint only; Linux is untested; restore and cross-OS artifact interchange remain unestablished. End-to-end execution from the packed package has not been host-tested. Real modal interactions and loading the packed package in OpenCode have not been verified. The checkpoint format may change; no compatibility, security, or platform-support guarantee is made.
 
 ## Commands
 
@@ -24,17 +24,17 @@ Add the plugin to the `plugins` array in your global CLI-only config (`cli.json`
 
 ```json
 {
-  "plugins": ["opencode-session-port@0.1.3"]
+  "plugins": ["opencode-session-port@0.1.4"]
 }
 ```
 
 Or install the package plugin with the OpenCode CLI:
 
 ```sh
-opencode plugin add opencode-session-port@0.1.3
+opencode plugin add opencode-session-port@0.1.4
 ```
 
-`cli.json` is the documented OpenCode v2 config for CLI-only plugins: they run locally in the terminal and remain active when the CLI connects to a remote server. No published tarball exists yet, so no published artifact has been loaded by OpenCode. The 0.1.1 tarball passed npm consumer checks, but a direct Bun package-manager install timed out in the verification environment, so that install path remains unverified. The 0.1.2 tarball passed manifest/allowlist and packed-entry checks only. The 0.1.3 metadata/platform-allowlist update has not been package-verified, published, or loaded by OpenCode.
+`cli.json` is the documented OpenCode v2 config for CLI-only plugins: they run locally in the terminal and remain active when the CLI connects to a remote server. The npm registry shows 0.1.2 and 0.1.3 published (0.1.3 latest; read-only registry check); no published artifact has been loaded by OpenCode here, and no local package-verification record exists for the published 0.1.3 tarball. The 0.1.1 tarball passed npm consumer checks, but a direct Bun package-manager install timed out in the verification environment, so that install path remains unverified. The 0.1.2 tarball passed manifest/allowlist and packed-entry checks only. The 0.1.4 candidate tarball passed the same local manifest/allowlist and packed-entry checks (including the sanitized collection-failure copy); it is not published.
 
 ## Usage
 

package/dist/tui.js

@@ -5866,7 +5866,7 @@ function reportCheckpointFailure(error) {
     case "capability":
       return checkpointFailure("This OpenCode host does not expose the required session-listing capability; no artifact was written.");
     case "collection":
-      return checkpointFailure("Collecting the project's sessions failed; no artifact was written.");
+      return checkpointFailure(checkpointCollectionFailureMessage(error));
     case "path-exists":
       return checkpointFailure("An artifact already exists at that path; nothing was overwritten.");
     case "artifact-path":
@@ -5885,6 +5885,15 @@ function reportCheckpointFailure(error) {
 function checkpointFailure(message) {
   return { title: "Checkpoint failed", message, variant: "error" };
 }
+function checkpointCollectionFailureMessage(error) {
+  if (!(error instanceof SessionCollectionError))
+    return CHECKPOINT_COLLECTION_FAILURE;
+  const code = error.code;
+  if (!Object.hasOwn(CHECKPOINT_COLLECTION_REASONS, code))
+    return CHECKPOINT_COLLECTION_FAILURE;
+  const reason = CHECKPOINT_COLLECTION_REASONS[code];
+  return `${CHECKPOINT_COLLECTION_FAILURE} Reason: ${reason} (${code}).`;
+}
 function reportRestoreUsage() {
   return {
     title: "Restore needs an artifact path",
@@ -6039,6 +6048,7 @@ function classifyFailure(error) {
   }
   return "unknown";
 }
+var CHECKPOINT_COLLECTION_FAILURE = "Collecting the project's sessions failed; no artifact was written.", CHECKPOINT_COLLECTION_REASONS;
 var init_reports = __esm(() => {
   init_files();
   init_adapters();
@@ -6047,6 +6057,25 @@ var init_reports = __esm(() => {
   init_planner();
   init_sessions();
   init_orchestration();
+  CHECKPOINT_COLLECTION_REASONS = {
+    "invalid-request": "the session collection request was invalid",
+    "invalid-policy": "the session collection policy was invalid",
+    "session-list-failed": "the host session list could not be read",
+    "message-list-failed": "a session's message history could not be read",
+    "malformed-session-page": "the host returned a malformed session list page",
+    "malformed-message-page": "the host returned a malformed message list page",
+    "malformed-session-record": "the host returned a malformed session record",
+    "malformed-message-record": "the host returned a malformed message record",
+    "session-project-mismatch": "a listed session did not belong to the requested project",
+    "duplicate-session-id": "the host returned a session more than once",
+    "duplicate-message-id": "the host returned a message more than once",
+    "repeated-session-cursor": "the host repeated a session list cursor",
+    "repeated-message-cursor": "the host repeated a message list cursor",
+    "session-limit-exceeded": "the session count exceeded the configured limit",
+    "message-limit-exceeded": "a session's message count exceeded the configured limit",
+    "total-message-limit-exceeded": "the total message count exceeded the configured limit",
+    "unsettled-message": "the project history contains an unfinished message"
+  };
 });
 
 // src/tui/wiring/composition.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-port",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "license": "MIT",
   "description": "SessionPort: experimental OpenCode TUI plugin for password-encrypted session checkpoint and restore.",

package/src/tui/wiring/reports.ts

@@ -4,7 +4,10 @@
  * Every function here returns a fixed, generic notification object; raw host
  * or exception text is NEVER interpolated. Classification uses stable error
  * classes/codes only, never message text, so a failure report cannot leak
- * session IDs, paths, host internals, or password material. Exact user-facing
+ * session IDs, paths, host internals, or password material. Checkpoint
+ * collection failures additionally append a fixed human reason and the exact
+ * machine code, but only for `SessionCollectionError` codes on an explicit
+ * allowlist; unknown or forged codes keep the generic text. Exact user-facing
  * copy remains OPEN (OQ-15); these strings are the wiring lane's generic
  * sanitized categories.
  *
@@ -31,7 +34,7 @@ import { HostAdapterError, ProjectDestinationError } from "../adapters/index.ts"
 import { LocationResolutionError } from "../adapters/location-resolver.ts";
 import { CryptoContainerError } from "../../core/crypto/errors.ts";
 import { RestorePlanError } from "../../core/restore/planner.ts";
-import { SessionCollectionError } from "../../core/sessions/index.ts";
+import { SessionCollectionError, type SessionCollectionErrorCode } from "../../core/sessions/index.ts";
 import { RESTORE_PASSWORD_ATTEMPT_LIMIT } from "../orchestration/index.ts";
 import type { CheckpointOutcome, RestoreExecutionResult } from "../orchestration/index.ts";
 import type {
@@ -94,7 +97,7 @@ export function reportCheckpointFailure(error: unknown): SessionPortNotification
 		case "capability":
 			return checkpointFailure("This OpenCode host does not expose the required session-listing capability; no artifact was written.");
 		case "collection":
-			return checkpointFailure("Collecting the project's sessions failed; no artifact was written.");
+			return checkpointFailure(checkpointCollectionFailureMessage(error));
 		case "path-exists":
 			return checkpointFailure("An artifact already exists at that path; nothing was overwritten.");
 		case "artifact-path":
@@ -116,6 +119,51 @@ function checkpointFailure(message: string): SessionPortNotification {
 	return { title: "Checkpoint failed", message, variant: "error" };
 }
 
+/** Existing generic checkpoint collection failure copy; also the fallback for unknown codes. */
+const CHECKPOINT_COLLECTION_FAILURE = "Collecting the project's sessions failed; no artifact was written.";
+
+/**
+ * Fixed human reason per known `SessionCollectionError` code. This record is
+ * the explicit allowlist: the raw code is echoed to the user only when it
+ * exactly matches one of these keys, and the raw `error.message` (which can
+ * contain session/project IDs, paths, and host error text) is never used.
+ * Adding a code to `SessionCollectionErrorCode` fails compilation until a
+ * fixed reason is added here.
+ */
+const CHECKPOINT_COLLECTION_REASONS: Readonly<Record<SessionCollectionErrorCode, string>> = {
+	"invalid-request": "the session collection request was invalid",
+	"invalid-policy": "the session collection policy was invalid",
+	"session-list-failed": "the host session list could not be read",
+	"message-list-failed": "a session's message history could not be read",
+	"malformed-session-page": "the host returned a malformed session list page",
+	"malformed-message-page": "the host returned a malformed message list page",
+	"malformed-session-record": "the host returned a malformed session record",
+	"malformed-message-record": "the host returned a malformed message record",
+	"session-project-mismatch": "a listed session did not belong to the requested project",
+	"duplicate-session-id": "the host returned a session more than once",
+	"duplicate-message-id": "the host returned a message more than once",
+	"repeated-session-cursor": "the host repeated a session list cursor",
+	"repeated-message-cursor": "the host repeated a message list cursor",
+	"session-limit-exceeded": "the session count exceeded the configured limit",
+	"message-limit-exceeded": "a session's message count exceeded the configured limit",
+	"total-message-limit-exceeded": "the total message count exceeded the configured limit",
+	"unsettled-message": "the project history contains an unfinished message",
+};
+
+/**
+ * Checkpoint collection failure copy: the existing generic message plus
+ * `Reason: <fixed human reason> (<known code>).` for a `SessionCollectionError`
+ * whose code is on the allowlist. Any other error or code keeps the generic
+ * text; only allowlisted literal code strings are ever echoed.
+ */
+function checkpointCollectionFailureMessage(error: unknown): string {
+	if (!(error instanceof SessionCollectionError)) return CHECKPOINT_COLLECTION_FAILURE;
+	const code: string = error.code;
+	if (!Object.hasOwn(CHECKPOINT_COLLECTION_REASONS, code)) return CHECKPOINT_COLLECTION_FAILURE;
+	const reason = CHECKPOINT_COLLECTION_REASONS[code as SessionCollectionErrorCode];
+	return `${CHECKPOINT_COLLECTION_FAILURE} Reason: ${reason} (${code}).`;
+}
+
 /* ------------------------------------------------------------------------- */
 /* Restore reports                                                           */
 /* ------------------------------------------------------------------------- */