opencode-session-port 0.1.3 → 0.1.5

package/README.md

@@ -4,12 +4,12 @@
 
 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.5).** 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 and 0.1.5 are local candidates (0.1.5 current). 0.1.4 was a diagnostics/copy patch: a failed checkpoint collection appends a fixed sanitized reason and the known machine code (`Reason: <fixed reason> (<code>).`) for the current collection codes; unknown codes keep the generic text and raw host/exception text is never shown. 0.1.5 adds a bare `/restore` default that uses the newest checkpoint in the current project's `.sessionport/` directory (newest file modification time; no fallback to an older artifact on a corrupt file, wrong password, or read failure) and extends the same fixed-reason diagnostics to known restore plan/collection error codes. Collector behavior is unchanged, and no root cause is established for an earlier Windows collection failure; the concrete code behind an earlier restore rejection is likewise still pending a user runtime observation, and no planner correctness fix is claimed. 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
 
 - **`/checkpoint [artifact-path]`** — collects the current project's sessions as returned by the host (child/subagent and archived sessions included when the host returns them) and writes one encrypted artifact. It fails cleanly, with no artifact, when the set is empty, a session cannot be captured completely, or the output file already exists.
-- **`/restore <artifact-path>`** — decrypts and validates the artifact before session imports, then restores it into an existing project you select. Restore does not overwrite existing sessions: exact destination matches are skipped, conflicting IDs are remapped deterministically, and parents are imported before children.
+- **`/restore [artifact-path]`** — decrypts and validates the artifact before session imports, then restores it into an existing project you select. Without a path, `/restore` uses the newest checkpoint in the current project's `.sessionport/` directory (newest file modification time; an exact tie is broken deterministically by filename). Restore does not overwrite existing sessions: exact destination matches are skipped, conflicting IDs are remapped deterministically, and parents are imported before children.
 
 Both commands are registered by the plugin as `sessionport.checkpoint` and `sessionport.restore`, and appear in the slash-command list and the command palette.
 
@@ -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.5"]
 }
 ```
 
 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.5
 ```
 
-`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 and 0.1.5 candidate tarballs passed the same local manifest/allowlist and packed-entry checks (0.1.5 including the bare-restore latest-checkpoint resolver and the restore reason-copy allowlists); neither is published by this repository lane.
 
 ## Usage
 
@@ -51,9 +51,11 @@ Checkpoint prompts for a password twice in a masked input (paste is allowed); bo
 ### Restore
 
 ```text
-/restore <artifact-path>
+/restore [artifact-path]
 ```
 
+Without an argument, `/restore` picks the newest checkpoint in the current project's `.sessionport/` directory (newest file modification time wins; an exact tie is broken deterministically by filename, descending). If the project has no active directory or no checkpoint is found, nothing is changed. Restore never falls back to an older checkpoint: a corrupt file, wrong password, or read failure stops the command with an error instead of trying another artifact.
+
 Restore first asks which existing project to import into, then prompts for the password (up to three attempts). The artifact is fully checked before the first session import. Project resolution may still update bounded host project metadata through OpenCode's public `location.get` API. Imports run parents-first, one session at a time: independent branches continue after a failure, descendants of a failed parent are blocked, and outcomes are reported per session. There is no atomic rollback. A later manual rerun may skip exact matching records, but exact retry behavior on a real host has not been established. Imported sessions are not opened or navigated to automatically.
 
 ### Moving artifacts

package/dist/tui.js

@@ -5710,7 +5710,7 @@ var init_experimental_profile = __esm(() => {
 });
 
 // src/tui/artifacts/files.ts
-import { lstat, mkdir, open, unlink } from "fs/promises";
+import { lstat, mkdir, open, readdir, unlink } from "fs/promises";
 import * as path from "path";
 async function resolveCheckpointOutputPath(options) {
   const input = options;
@@ -5761,6 +5761,51 @@ async function assertPathDoesNotExist(candidate) {
 function isErrnoCode(value, code) {
   return typeof value === "object" && value !== null && value.code === code;
 }
+async function resolveLatestCheckpointArtifact(options) {
+  const input = options;
+  if (typeof input !== "object" || input === null) {
+    throw new ArtifactFileError("invalid-request", "resolveLatestCheckpointArtifact options must be an object");
+  }
+  const projectDirectory = requireNonEmptyString3(input.projectDirectory, "projectDirectory");
+  const directory = path.resolve(projectDirectory, CHECKPOINT_DIRECTORY_NAME);
+  let directoryStats;
+  try {
+    directoryStats = await lstat(directory);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT"))
+      return;
+    throw error;
+  }
+  if (directoryStats.isSymbolicLink() || !directoryStats.isDirectory()) {
+    throw new ArtifactFileError("invalid-request", "The project's .sessionport checkpoint location is not a regular directory; refusing to scan it");
+  }
+  let bestName;
+  let bestMtimeMs = Number.NEGATIVE_INFINITY;
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (!entry.name.endsWith(CHECKPOINT_FILENAME_EXTENSION))
+      continue;
+    if (entry.isDirectory() || entry.isSymbolicLink())
+      continue;
+    let candidateStats;
+    try {
+      candidateStats = await lstat(path.join(directory, entry.name));
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT"))
+        continue;
+      throw error;
+    }
+    if (!candidateStats.isFile())
+      continue;
+    const mtimeMs = candidateStats.mtimeMs;
+    if (!Number.isFinite(mtimeMs))
+      continue;
+    if (bestName === undefined || mtimeMs > bestMtimeMs || mtimeMs === bestMtimeMs && entry.name > bestName) {
+      bestName = entry.name;
+      bestMtimeMs = mtimeMs;
+    }
+  }
+  return bestName === undefined ? undefined : path.join(directory, bestName);
+}
 async function writeEncryptedArtifact(targetPath, source) {
   const pathString = requireNonEmptyString3(targetPath, "path");
   const handle = await open(pathString, "wx");
@@ -5866,7 +5911,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,10 +5930,36 @@ function reportCheckpointFailure(error) {
 function checkpointFailure(message) {
   return { title: "Checkpoint failed", message, variant: "error" };
 }
+function checkpointCollectionFailureMessage(error) {
+  return withKnownCollectionReason(error, CHECKPOINT_COLLECTION_FAILURE);
+}
+function withKnownCollectionReason(error, base) {
+  if (!(error instanceof SessionCollectionError))
+    return base;
+  const code = error.code;
+  if (!Object.hasOwn(COLLECTION_FAILURE_REASONS, code))
+    return base;
+  const reason = COLLECTION_FAILURE_REASONS[code];
+  return `${base} Reason: ${reason} (${code}).`;
+}
 function reportRestoreUsage() {
   return {
-    title: "Restore needs an artifact path",
-    message: "Usage: /restore <path-to-checkpoint>. No sessions were changed.",
+    title: "Restore usage",
+    message: "Usage: /restore [artifact-path]. Without a path, the newest checkpoint in the current project's .sessionport directory is used. No sessions were changed.",
+    variant: "warning"
+  };
+}
+function reportRestoreNoActiveProject() {
+  return {
+    title: "Restore unavailable",
+    message: "The active project directory is unavailable, so the latest checkpoint could not be found; no sessions were changed.",
+    variant: "warning"
+  };
+}
+function reportRestoreNoCheckpointFound() {
+  return {
+    title: "No checkpoint found",
+    message: "No checkpoint artifact was found in the current project's .sessionport directory; no sessions were changed. Create one with /checkpoint or pass an artifact path to /restore.",
     variant: "warning"
   };
 }
@@ -5913,6 +5984,18 @@ function reportRestoreAuthenticationFailed() {
     variant: "error"
   };
 }
+function restoreCollectionFailureMessage(error) {
+  return withKnownCollectionReason(error, RESTORE_COLLECTION_FAILURE);
+}
+function restorePlanFailureMessage(error) {
+  if (!(error instanceof RestorePlanError))
+    return RESTORE_PLAN_FAILURE;
+  const code = error.code;
+  if (!Object.hasOwn(RESTORE_PLAN_REASONS, code))
+    return RESTORE_PLAN_FAILURE;
+  const reason = RESTORE_PLAN_REASONS[code];
+  return `${RESTORE_PLAN_FAILURE} Reason: ${reason} (${code}).`;
+}
 function reportRestoreFailure(error, executionStarted) {
   if (executionStarted) {
     return {
@@ -5932,9 +6015,9 @@ function reportRestoreFailure(error, executionStarted) {
     case "destinations":
       return restoreFailure("The host project list could not be read; no sessions were changed.");
     case "collection":
-      return restoreFailure("The destination project's sessions could not be read; no sessions were changed.");
+      return restoreFailure(restoreCollectionFailureMessage(error));
     case "plan":
-      return restoreFailure("The checkpoint does not match this destination safely; no sessions were changed.");
+      return restoreFailure(restorePlanFailureMessage(error));
     case "artifact-path":
       return restoreFailure("The artifact path is not usable; no sessions were changed.");
     case "path-exists":
@@ -6039,6 +6122,7 @@ function classifyFailure(error) {
   }
   return "unknown";
 }
+var CHECKPOINT_COLLECTION_FAILURE = "Collecting the project's sessions failed; no artifact was written.", COLLECTION_FAILURE_REASONS, RESTORE_COLLECTION_FAILURE = "The destination project's sessions could not be read; no sessions were changed.", RESTORE_PLAN_FAILURE = "The checkpoint does not match this destination safely; no sessions were changed.", RESTORE_PLAN_REASONS;
 var init_reports = __esm(() => {
   init_files();
   init_adapters();
@@ -6047,6 +6131,39 @@ var init_reports = __esm(() => {
   init_planner();
   init_sessions();
   init_orchestration();
+  COLLECTION_FAILURE_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"
+  };
+  RESTORE_PLAN_REASONS = {
+    "invalid-input": "the restore planning request was invalid",
+    "malformed-payload": "the checkpoint payload was malformed",
+    "malformed-destination": "the destination session history could not be read",
+    "divergent-artifact-session": "the checkpoint repeats a session with different content",
+    "duplicate-artifact-message-id": "the checkpoint repeats a message ID across sessions",
+    "ambiguous-destination": "the destination repeats a session or message ID",
+    "dangling-session-reference": "a session reference does not resolve in the destination or plan",
+    "dangling-message-reference": "a message reference does not resolve in the destination",
+    "session-id-collision": "a planned session ID collides with existing session history",
+    "message-id-collision": "a planned message ID collides with existing session history",
+    "dependency-cycle": "session parent/reference relationships contain a cycle",
+    "derivation-failure": "a remapped session or message ID could not be derived"
+  };
 });
 
 // src/tui/wiring/composition.ts
@@ -6059,6 +6176,7 @@ function createSessionPortHandlers(dependencies) {
   requireCallable(dependencies.showRestoreReport, "showRestoreReport");
   requireCallable(dependencies.requestPassword, "requestPassword");
   requireCallable(dependencies.resolveCheckpointOutputPath, "resolveCheckpointOutputPath");
+  requireCallable(dependencies.resolveLatestCheckpointArtifact, "resolveLatestCheckpointArtifact");
   requireCallable(dependencies.writeEncryptedArtifact, "writeEncryptedArtifact");
   requireCallable(dependencies.readEncryptedArtifact, "readEncryptedArtifact");
   if (!isRecordValue(dependencies.cryptoFactory) || typeof dependencies.cryptoFactory.create !== "function") {
@@ -6105,11 +6223,7 @@ async function runCheckpointCommand(dependencies, rawInput) {
   }
 }
 async function runRestoreCommand(dependencies, rawInput) {
-  const artifactPath = parseRestoreArtifactArgument(rawInput);
-  if (artifactPath === undefined) {
-    dependencies.notify(reportRestoreUsage());
-    return;
-  }
+  const explicitArtifactPath = parseRestoreArtifactArgument(rawInput);
   const capability = probeSessionImportCapability(dependencies.client);
   if (!capability.available) {
     dependencies.notify(reportRestoreCapabilityUnavailable());
@@ -6117,6 +6231,22 @@ async function runRestoreCommand(dependencies, rawInput) {
   }
   let executionStarted = false;
   try {
+    let artifactPath;
+    if (explicitArtifactPath !== undefined) {
+      artifactPath = explicitArtifactPath;
+    } else {
+      const activeDirectory = dependencies.getActiveDirectory();
+      if (typeof activeDirectory !== "string" || activeDirectory.trim().length === 0) {
+        dependencies.notify(reportRestoreNoActiveProject());
+        return;
+      }
+      const latest = await dependencies.resolveLatestCheckpointArtifact({ projectDirectory: activeDirectory });
+      if (latest === undefined) {
+        dependencies.notify(reportRestoreNoCheckpointFound());
+        return;
+      }
+      artifactPath = latest;
+    }
     const destinations = await createProjectDestinationsAdapter(dependencies.client).listDestinations();
     const selected = await selectRestoreProject(dependencies.dialog, destinations);
     if (selected === undefined) {
@@ -10214,6 +10344,7 @@ async function installSessionPortWiring(context, options = {}) {
     cryptoFactory,
     idDeriver,
     resolveCheckpointOutputPath,
+    resolveLatestCheckpointArtifact,
     writeEncryptedArtifact,
     readEncryptedArtifact
   });
@@ -10239,6 +10370,8 @@ var init_install = __esm(() => {
 var exports_wiring = {};
 __export(exports_wiring, {
   reportRestoreUsage: () => reportRestoreUsage,
+  reportRestoreNoCheckpointFound: () => reportRestoreNoCheckpointFound,
+  reportRestoreNoActiveProject: () => reportRestoreNoActiveProject,
   reportRestoreFailure: () => reportRestoreFailure,
   reportRestoreExecution: () => reportRestoreExecution,
   reportRestoreCapabilityUnavailable: () => reportRestoreCapabilityUnavailable,

package/package.json

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

package/src/tui/artifacts/files.ts

@@ -40,10 +40,16 @@
  *   `:` from the UTC timestamp, no reserved device name), and drive-relative
  *   explicit paths (`C:foo`) fail closed instead of silently anchoring to the
  *   per-drive current directory.
+ * - `resolveLatestCheckpointArtifact` implements the bare `/restore` default:
+ *   a non-recursive, content-free scan of `<projectDirectory>/.sessionport/`
+ *   (newest `mtimeMs` wins; an exact tie is broken by filename, descending
+ *   code-unit order). It never creates, opens, or reads a file, excludes
+ *   symlink/swapped entries, and refuses a non-regular `.sessionport` entry
+ *   instead of traversing it.
  */
 
 /// <reference types="node" />
-import { lstat, mkdir, open, unlink } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, unlink } from "node:fs/promises";
 import * as path from "node:path";
 import type { ByteSource } from "../../core/contracts/index.ts";
 
@@ -187,6 +193,93 @@ function isErrnoCode(value: unknown, code: string): boolean {
 	return typeof value === "object" && value !== null && (value as { readonly code?: unknown }).code === code;
 }
 
+/* ------------------------------------------------------------------------- */
+/* Latest-checkpoint discovery (bare `/restore`)                             */
+/* ------------------------------------------------------------------------- */
+
+/** Options for `resolveLatestCheckpointArtifact`. */
+export interface ResolveLatestCheckpointArtifactOptions {
+	/** Current project directory; the default checkpoint directory sits beneath it. */
+	readonly projectDirectory: string;
+}
+
+/**
+ * Resolves the newest default checkpoint artifact under
+ * `<projectDirectory>/.sessionport/`, or `undefined` when that directory is
+ * missing or contains no candidate. Selection is non-recursive and
+ * content-free: only entries whose name ends in the exact `.sessionport`
+ * suffix are considered (no prefix required), a candidate must be a regular
+ * file by `lstat` at selection time (symlinks and entries swapped after
+ * `readdir` are excluded), and only finite modification times qualify. The
+ * newest `mtimeMs` wins; an exact tie is broken by filename, descending
+ * UTF-16 code-unit order (deterministic, never locale-dependent). Nothing is
+ * created, opened, or read.
+ *
+ * Fail-closed behavior: a `.sessionport` entry that is not a regular
+ * directory (symlink/junction/file) is refused, not traversed. A missing
+ * directory, an empty directory, or a scan with no candidate resolves
+ * `undefined`; every other filesystem error (for example permissions)
+ * propagates unchanged to the caller's sanitized failure reporting. A
+ * candidate that disappears during the scan (ENOENT) is skipped; unrelated
+ * errors are never suppressed. This is a best-effort local discovery helper:
+ * it does not promise race-freedom against a malicious filesystem writer
+ * beyond the `lstat` re-check and the existing read safeguards.
+ */
+export async function resolveLatestCheckpointArtifact(
+	options: ResolveLatestCheckpointArtifactOptions,
+): Promise<string | undefined> {
+	const input: unknown = options;
+	if (typeof input !== "object" || input === null) {
+		throw new ArtifactFileError("invalid-request", "resolveLatestCheckpointArtifact options must be an object");
+	}
+	const projectDirectory = requireNonEmptyString(
+		(input as { readonly projectDirectory?: unknown }).projectDirectory,
+		"projectDirectory",
+	);
+
+	const directory = path.resolve(projectDirectory, CHECKPOINT_DIRECTORY_NAME);
+	let directoryStats;
+	try {
+		// lstat: a symlinked/junction directory is never followed or traversed.
+		directoryStats = await lstat(directory);
+	} catch (error) {
+		if (isErrnoCode(error, "ENOENT")) return undefined;
+		throw error;
+	}
+	if (directoryStats.isSymbolicLink() || !directoryStats.isDirectory()) {
+		throw new ArtifactFileError(
+			"invalid-request",
+			"The project's .sessionport checkpoint location is not a regular directory; refusing to scan it",
+		);
+	}
+
+	let bestName: string | undefined;
+	let bestMtimeMs = Number.NEGATIVE_INFINITY;
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (!entry.name.endsWith(CHECKPOINT_FILENAME_EXTENSION)) continue;
+		// Dirent-level exclusion first; the lstat below is authoritative for
+		// the rest (including entries whose dirent type is unknown).
+		if (entry.isDirectory() || entry.isSymbolicLink()) continue;
+		let candidateStats;
+		try {
+			// Re-check after readdir: the entry may have been swapped for a
+			// symlink or a different object between the two calls.
+			candidateStats = await lstat(path.join(directory, entry.name));
+		} catch (error) {
+			if (isErrnoCode(error, "ENOENT")) continue;
+			throw error;
+		}
+		if (!candidateStats.isFile()) continue;
+		const mtimeMs = candidateStats.mtimeMs;
+		if (!Number.isFinite(mtimeMs)) continue;
+		if (bestName === undefined || mtimeMs > bestMtimeMs || (mtimeMs === bestMtimeMs && entry.name > bestName)) {
+			bestName = entry.name;
+			bestMtimeMs = mtimeMs;
+		}
+	}
+	return bestName === undefined ? undefined : path.join(directory, bestName);
+}
+
 /* ------------------------------------------------------------------------- */
 /* Exclusive write / lazy read                                               */
 /* ------------------------------------------------------------------------- */

package/src/tui/wiring/composition.ts

@@ -12,10 +12,16 @@
  *      resolution, seal, exclusive encrypted write;
  *   3. report path/size/session-count facts or a sanitized failure.
  *
- * `/restore <artifact-path>`
- *   1. require the artifact path argument (nothing runs without it);
- *   2. probe `session.import` capability FIRST — before any artifact read,
- *      decrypt, or import (O-12);
+ * `/restore [artifact-path]`
+ *   1. probe `session.import` capability FIRST — before any filesystem
+ *      discovery, artifact read, decrypt, or import (O-12, both forms);
+ *   2. when no artifact path is given (bare `/restore`), read the active
+ *      project directory, fail closed with fixed copy when it is unavailable,
+ *      and resolve the newest checkpoint in that project's `.sessionport/`
+ *      directory through the injected resolver; no latest file reports a
+ *      fixed no-checkpoint copy. An explicit path bypasses this lookup (and
+ *      the active-directory read) entirely. No active `location.get` and no
+ *      automatic destination selection are used for either form;
  *   3. enumerate existing host projects via `project.list`, let the user select
  *      with `selectRestoreProject`;
  *   4. call `location.get` ONLY for the selected candidate and require an exact
@@ -33,6 +39,9 @@
  *      empty result keeps the truthful non-success notification, and a
  *      dialog-display failure falls back to bounded aggregate-only copy.
  *
+ * No fallback artifact: a corrupt file, wrong password, or read failure stops
+ * the command; an older checkpoint is never silently substituted.
+ *
  * Hard boundaries: no shell/Git, no LLM/model call, no historical tool replay,
  * no direct database access, no `project.update`; passwords stay masked and are
  * owned/zeroed by the orchestration helpers; only already-sealed ciphertext is
@@ -47,7 +56,7 @@
 import type { ByteSource, CheckpointCryptoFactory } from "../../core/contracts/index.ts";
 import { collectCheckpointPayload } from "../../core/sessions/index.ts";
 import type { RemappedIdDeriver } from "../../core/restore/index.ts";
-import type { ResolveCheckpointOutputPathOptions } from "../artifacts/files.ts";
+import type { ResolveCheckpointOutputPathOptions, ResolveLatestCheckpointArtifactOptions } from "../artifacts/files.ts";
 import { createLocationResolver, LocationResolutionError } from "../adapters/location-resolver.ts";
 import { createProjectDestinationsAdapter } from "../adapters/project-destinations.ts";
 import { createSessionIdInventory } from "../adapters/session-id-inventory.ts";
@@ -78,7 +87,8 @@ import {
 	reportRestoreExecution,
 	reportRestoreExecutionFallback,
 	reportRestoreFailure,
-	reportRestoreUsage,
+	reportRestoreNoActiveProject,
+	reportRestoreNoCheckpointFound,
 	type SessionPortNotification,
 } from "./reports.ts";
 
@@ -118,6 +128,15 @@ export interface SessionPortHandlerDependencies {
 	readonly idDeriver: RemappedIdDeriver;
 	/** P-15 artifact output-path resolver. */
 	readonly resolveCheckpointOutputPath: (options: ResolveCheckpointOutputPathOptions) => Promise<string>;
+	/**
+	 * Bare `/restore` latest-artifact resolver: newest `.sessionport` artifact
+	 * under the project's default `.sessionport/` directory, or `undefined`
+	 * when none exists. Production uses the filesystem resolver; tests inject a
+	 * fake so no real discovery happens.
+	 */
+	readonly resolveLatestCheckpointArtifact: (
+		options: ResolveLatestCheckpointArtifactOptions,
+	) => Promise<string | undefined>;
 	/** Exclusive encrypted-artifact writer (ciphertext only). */
 	readonly writeEncryptedArtifact: (targetPath: string, source: ByteSource) => Promise<number>;
 	/** Lazy encrypted-artifact reader (no IO until iterated). */
@@ -142,6 +161,7 @@ export function createSessionPortHandlers(dependencies: SessionPortHandlerDepend
 	requireCallable(dependencies.showRestoreReport, "showRestoreReport");
 	requireCallable(dependencies.requestPassword, "requestPassword");
 	requireCallable(dependencies.resolveCheckpointOutputPath, "resolveCheckpointOutputPath");
+	requireCallable(dependencies.resolveLatestCheckpointArtifact, "resolveLatestCheckpointArtifact");
 	requireCallable(dependencies.writeEncryptedArtifact, "writeEncryptedArtifact");
 	requireCallable(dependencies.readEncryptedArtifact, "readEncryptedArtifact");
 	if (!isRecordValue(dependencies.cryptoFactory) || typeof dependencies.cryptoFactory.create !== "function") {
@@ -209,14 +229,12 @@ async function runRestoreCommand(
 	dependencies: SessionPortHandlerDependencies,
 	rawInput: string | undefined,
 ): Promise<void> {
-	const artifactPath = parseRestoreArtifactArgument(rawInput);
-	if (artifactPath === undefined) {
-		dependencies.notify(reportRestoreUsage());
-		return;
-	}
+	// `undefined` means no explicit path: bare `/restore` uses the newest
+	// checkpoint in the active project's `.sessionport/` directory.
+	const explicitArtifactPath = parseRestoreArtifactArgument(rawInput);
 
-	// O-12: capability absence is the first check — before any file read,
-	// decrypt, destination enumeration, or import.
+	// O-12: capability absence is the first check — before any filesystem
+	// discovery, file read, decrypt, destination enumeration, or import.
 	const capability = probeSessionImportCapability(dependencies.client);
 	if (!capability.available) {
 		dependencies.notify(reportRestoreCapabilityUnavailable());
@@ -225,6 +243,24 @@ async function runRestoreCommand(
 
 	let executionStarted = false;
 	try {
+		let artifactPath: string;
+		if (explicitArtifactPath !== undefined) {
+			// Explicit paths bypass the active-project lookup entirely.
+			artifactPath = explicitArtifactPath;
+		} else {
+			const activeDirectory = dependencies.getActiveDirectory();
+			if (typeof activeDirectory !== "string" || activeDirectory.trim().length === 0) {
+				dependencies.notify(reportRestoreNoActiveProject());
+				return;
+			}
+			const latest = await dependencies.resolveLatestCheckpointArtifact({ projectDirectory: activeDirectory });
+			if (latest === undefined) {
+				dependencies.notify(reportRestoreNoCheckpointFound());
+				return;
+			}
+			artifactPath = latest;
+		}
+
 		// Candidate enumeration and user selection happen before any location.get
 		// or artifact access; a canceled selection changes nothing.
 		const destinations = await createProjectDestinationsAdapter(dependencies.client).listDestinations();
@@ -342,10 +378,11 @@ export function parseCheckpointOutputArgument(rawInput: string | undefined): str
 }
 
 /**
- * `/restore` requires one raw argument: the artifact path. `undefined` or an
- * all-whitespace argument yields `undefined` so the caller reports usage
- * without touching the host; any other argument is trimmed of surrounding
- * whitespace and used verbatim.
+ * `/restore` accepts one optional raw argument: the artifact path. `undefined`
+ * or an all-whitespace argument means the bare form (newest checkpoint in the
+ * active project's `.sessionport/` directory); any other argument is trimmed
+ * of surrounding whitespace and used verbatim (no flag parsing, no shell
+ * expansion, no quote handling).
  */
 export function parseRestoreArtifactArgument(rawInput: string | undefined): string | undefined {
 	if (rawInput === undefined) return undefined;

package/src/tui/wiring/index.ts

@@ -47,6 +47,8 @@ export {
 	reportRestoreCapabilityUnavailable,
 	reportRestoreExecution,
 	reportRestoreFailure,
+	reportRestoreNoActiveProject,
+	reportRestoreNoCheckpointFound,
 	reportRestoreUsage,
 } from "./reports.ts";
 export type { SessionPortNotification, SessionPortNotificationVariant } from "./reports.ts";

package/src/tui/wiring/install.ts

@@ -41,7 +41,7 @@ import type { Plugin } from "@opencode/plugin/tui";
 import type { CheckpointCryptoFactory } from "../../core/contracts/index.ts";
 import { createCheckpointCryptoFactory } from "../../core/crypto/index.ts";
 import { createRemappedIdDeriver, type RemappedIdDeriver } from "../../core/restore/index.ts";
-import { readEncryptedArtifact, resolveCheckpointOutputPath, writeEncryptedArtifact } from "../artifacts/files.ts";
+import { readEncryptedArtifact, resolveCheckpointOutputPath, resolveLatestCheckpointArtifact, writeEncryptedArtifact } from "../artifacts/files.ts";
 import { requestPassword as showPasswordDialog } from "../ui/password-dialog.tsx";
 import { showRestoreReportDialog } from "../ui/restore-report-dialog.tsx";
 import { installSessionPortCommands } from "../ui/sessionport-commands.tsx";
@@ -99,6 +99,7 @@ export async function installSessionPortWiring(
 		cryptoFactory,
 		idDeriver,
 		resolveCheckpointOutputPath,
+		resolveLatestCheckpointArtifact,
 		writeEncryptedArtifact,
 		readEncryptedArtifact,
 	});

package/src/tui/wiring/reports.ts

@@ -4,7 +4,11 @@
  * 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, restore collection failures, and restore plan failures
+ * additionally append a fixed human reason and the exact machine code, but
+ * only for `SessionCollectionError`/`RestorePlanError` codes on explicit
+ * allowlists; 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.
  *
@@ -30,8 +34,8 @@ import { ArtifactFileError } from "../artifacts/files.ts";
 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 { RestorePlanError, type RestorePlanErrorCode } from "../../core/restore/planner.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 +98,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,15 +120,103 @@ 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 shared explicit allowlist for both the checkpoint and the restore
+ * collection category: 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 COLLECTION_FAILURE_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 {
+	return withKnownCollectionReason(error, CHECKPOINT_COLLECTION_FAILURE);
+}
+
+/**
+ * Shared allowlist lookup for collection failures: appends
+ * `Reason: <fixed human reason> (<known code>).` to `base` for a
+ * `SessionCollectionError` whose code is on the fixed map. Any other error,
+ * non-instance object, or unknown/forged code keeps `base` unchanged; only
+ * allowlisted literal code strings are ever echoed.
+ */
+function withKnownCollectionReason(error: unknown, base: string): string {
+	if (!(error instanceof SessionCollectionError)) return base;
+	const code: string = error.code;
+	if (!Object.hasOwn(COLLECTION_FAILURE_REASONS, code)) return base;
+	const reason = COLLECTION_FAILURE_REASONS[code as SessionCollectionErrorCode];
+	return `${base} Reason: ${reason} (${code}).`;
+}
+
 /* ------------------------------------------------------------------------- */
 /* Restore reports                                                           */
 /* ------------------------------------------------------------------------- */
 
-/** The artifact path argument is required; nothing was read or changed. */
+/**
+ * Exported for compatibility. Bare `/restore` now resolves the newest
+ * checkpoint automatically, so the current wiring does not show this usage
+ * copy; it documents the optional artifact-path argument.
+ */
 export function reportRestoreUsage(): SessionPortNotification {
 	return {
-		title: "Restore needs an artifact path",
-		message: "Usage: /restore <path-to-checkpoint>. No sessions were changed.",
+		title: "Restore usage",
+		message:
+			"Usage: /restore [artifact-path]. Without a path, the newest checkpoint in the current project's .sessionport directory is used. No sessions were changed.",
+		variant: "warning",
+	};
+}
+
+/**
+ * Bare `/restore` with no active project directory: fixed, specific copy with
+ * no raw path/error text; nothing was read or changed.
+ */
+export function reportRestoreNoActiveProject(): SessionPortNotification {
+	return {
+		title: "Restore unavailable",
+		message:
+			"The active project directory is unavailable, so the latest checkpoint could not be found; no sessions were changed.",
+		variant: "warning",
+	};
+}
+
+/**
+ * Bare `/restore` with no checkpoint in the active project's default
+ * `.sessionport/` directory: fixed friendly copy; nothing was read or changed.
+ */
+export function reportRestoreNoCheckpointFound(): SessionPortNotification {
+	return {
+		title: "No checkpoint found",
+		message:
+			"No checkpoint artifact was found in the current project's .sessionport directory; no sessions were changed. Create one with /checkpoint or pass an artifact path to /restore.",
 		variant: "warning",
 	};
 }
@@ -157,6 +249,59 @@ export function reportRestoreAuthenticationFailed(): SessionPortNotification {
 	};
 }
 
+/** Existing generic restore collection failure copy; also the fallback for unknown codes. */
+const RESTORE_COLLECTION_FAILURE = "The destination project's sessions could not be read; no sessions were changed.";
+
+/** Existing generic restore plan failure copy; also the fallback for unknown codes. */
+const RESTORE_PLAN_FAILURE = "The checkpoint does not match this destination safely; no sessions were changed.";
+
+/**
+ * Fixed human reason per known `RestorePlanError` code — the explicit
+ * allowlist for the restore plan category. As with collection codes, the raw
+ * code is echoed only on an exact key match and the raw `error.message` (which
+ * can contain session/message IDs and labels) is never used. Adding a code to
+ * `RestorePlanErrorCode` fails compilation until a fixed reason is added here.
+ */
+const RESTORE_PLAN_REASONS: Readonly<Record<RestorePlanErrorCode, string>> = {
+	"invalid-input": "the restore planning request was invalid",
+	"malformed-payload": "the checkpoint payload was malformed",
+	"malformed-destination": "the destination session history could not be read",
+	"divergent-artifact-session": "the checkpoint repeats a session with different content",
+	"duplicate-artifact-message-id": "the checkpoint repeats a message ID across sessions",
+	"ambiguous-destination": "the destination repeats a session or message ID",
+	"dangling-session-reference": "a session reference does not resolve in the destination or plan",
+	"dangling-message-reference": "a message reference does not resolve in the destination",
+	"session-id-collision": "a planned session ID collides with existing session history",
+	"message-id-collision": "a planned message ID collides with existing session history",
+	"dependency-cycle": "session parent/reference relationships contain a cycle",
+	"derivation-failure": "a remapped session or message ID could not be derived",
+};
+
+/**
+ * Restore collection failure copy: the existing restore base message plus
+ * `Reason: <fixed human reason> (<known code>).` for a known
+ * `SessionCollectionError` code (shared allowlist with the checkpoint
+ * category). Unknown/forged codes and non-instance errors keep the base text;
+ * raw messages, IDs, and paths never leak.
+ */
+function restoreCollectionFailureMessage(error: unknown): string {
+	return withKnownCollectionReason(error, RESTORE_COLLECTION_FAILURE);
+}
+
+/**
+ * Restore plan failure copy: the existing restore base message plus
+ * `Reason: <fixed human reason> (<known code>).` for a `RestorePlanError`
+ * whose code is on the allowlist. Unknown/forged codes and non-instance
+ * errors keep the base text; raw plan messages (IDs/labels) never leak.
+ */
+function restorePlanFailureMessage(error: unknown): string {
+	if (!(error instanceof RestorePlanError)) return RESTORE_PLAN_FAILURE;
+	const code: string = error.code;
+	if (!Object.hasOwn(RESTORE_PLAN_REASONS, code)) return RESTORE_PLAN_FAILURE;
+	const reason = RESTORE_PLAN_REASONS[code as RestorePlanErrorCode];
+	return `${RESTORE_PLAN_FAILURE} Reason: ${reason} (${code}).`;
+}
+
 /**
  * Reports one restore failure as a fixed, sanitized category. `executionStarted`
  * is true only once the import executor was invoked; the copy never claims
@@ -184,9 +329,9 @@ export function reportRestoreFailure(error: unknown, executionStarted: boolean):
 		case "destinations":
 			return restoreFailure("The host project list could not be read; no sessions were changed.");
 		case "collection":
-			return restoreFailure("The destination project's sessions could not be read; no sessions were changed.");
+			return restoreFailure(restoreCollectionFailureMessage(error));
 		case "plan":
-			return restoreFailure("The checkpoint does not match this destination safely; no sessions were changed.");
+			return restoreFailure(restorePlanFailureMessage(error));
 		case "artifact-path":
 			return restoreFailure("The artifact path is not usable; no sessions were changed.");
 		case "path-exists":