feat: auto-restore sessions opened in provider GUI (Fixes #32)

README.md

@@ -240,11 +240,14 @@ npx --yes agent-session-pack open --provider grok <session-id> --json
 npx --yes agent-session-pack maintain --apply --yes --json
 ```
 
-Provider wrappers (codex, claude, grok, …) run `preflight` so session ids in argv are
-auto-restored before the real binary starts. Live files that differ from the archive are
-**never** overwritten (`conflict`). Disable with `lifecycle disable` (removes wrappers).
+Provider wrappers (codex, claude, grok, …) run `preflight` (session ids on the command line)
+and **`watch`** while the app runs. Packed sessions leave tiny **stubs** so they stay listable;
+when the app opens a stub (GUI session pick), watch materializes the full archive automatically.
 
-**Manual path (always available):** `unpack` / `restore` without lifecycle.
+Live files that differ from the archive are **never** overwritten (`conflict`). Disable with
+`lifecycle disable` (removes wrappers).
+
+**Manual path (always available):** `unpack` / `restore` / `open` without relying on wrappers.
 </details>
 
 <details>

src/cli/commands/packAllProvidersCommand.test.ts

@@ -1,4 +1,4 @@
-import { copyFile, mkdir, mkdtemp, readFile, stat, utimes, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, readFile, utimes, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Effect } from 'effect';
@@ -80,7 +80,9 @@ describe('all-provider pack and unpack commands', () => {
       }),
     );
 
-    await expect(stat(session.path)).rejects.toMatchObject({ code: 'ENOENT' });
+    await expect(readFile(session.path, 'utf8')).resolves.toContain(
+      'agent-session-pack-archived-stub',
+    );
     await expect(
       readFile(join(vaultPath, 'manifests', 'codex', 'session-old.json'), 'utf8'),
     ).resolves.toContain(session.path);

src/cli/commands/watchCommand.ts

@@ -0,0 +1,221 @@
+import { spawn } from 'node:child_process';
+import { defineCommand } from 'citty';
+import { Effect, Schema } from 'effect';
+import { createZstdCompression } from '../../core/archiveReader.js';
+import type {
+  ArchiveFileSystemError,
+  ArchiveVerificationError,
+  CompressionAdapter,
+} from '../../core/archiveWriter.js';
+import type { ManifestStoreError } from '../../core/manifestStore.js';
+import { resolveDefaultVaultPath } from '../../core/sessionArchive.js';
+import { type ProviderId, ProviderIdSchema } from '../../core/sessionStore.js';
+import {
+  type SessionWatchError,
+  type SessionWatchEvent,
+  watchSessionStubs,
+} from '../../core/sessionWatch.js';
+import {
+  isRestoreOnLaunchEnabled,
+  readSetupConfig,
+  type SetupConfigFileError,
+} from '../../core/setupConfig.js';
+import { HOME_NOT_SET_STDERR_MESSAGE } from '../homeEnv.js';
+
+/**
+ * Citty command that watches archived stubs and restores sessions when opened.
+ */
+export const watchCommand = defineCommand({
+  meta: {
+    name: 'watch',
+    description:
+      'Watch archived session stubs and auto-restore when a provider opens them (GUI-friendly).',
+  },
+  args: {
+    provider: {
+      type: 'string',
+      description:
+        'Provider id: codex, claude, kiro, grok, kimi, opencode, gemini, cursor, or devin.',
+    },
+    json: {
+      type: 'boolean',
+      description: 'Write JSON lines for restore events.',
+    },
+    'poll-ms': {
+      type: 'string',
+      description: 'Poll interval in milliseconds (default 750).',
+    },
+  },
+  run: async ({ args, rawArgs }) => {
+    const execArgs = extractExecArgs(rawArgs);
+    await Effect.runPromise(
+      runWatchCommand({
+        provider: args.provider,
+        json: args.json,
+        pollMs: args['poll-ms'],
+        execArgv: execArgs,
+      }),
+    );
+  },
+});
+
+/**
+ * Decoded arguments for watch.
+ */
+export type WatchArgs = {
+  readonly provider: string | undefined;
+  readonly json: boolean | undefined;
+  readonly pollMs: string | undefined;
+  readonly execArgv: ReadonlyArray<string>;
+  readonly compression?: CompressionAdapter | undefined;
+  readonly home?: string | undefined;
+  readonly vaultPath?: string | undefined;
+};
+
+/**
+ * Runs session stub watch, optionally following a child provider process.
+ *
+ * @param args - Provider filter, poll interval, and optional exec argv.
+ * @returns Effect that completes when watch stops (child exit or signal).
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { runWatchCommand } from './watchCommand.js';
+ *
+ * await Effect.runPromise(
+ *   runWatchCommand({
+ *     provider: 'grok',
+ *     json: true,
+ *     pollMs: '500',
+ *     execArgv: [],
+ *   }),
+ * );
+ * ```
+ */
+export const runWatchCommand = (
+  args: WatchArgs,
+): Effect.Effect<
+  void,
+  | ArchiveFileSystemError
+  | ArchiveVerificationError
+  | ManifestStoreError
+  | SessionWatchError
+  | SetupConfigFileError
+> =>
+  Effect.gen(function* () {
+    const home = args.home ?? process.env.HOME;
+
+    if (home === undefined) {
+      process.stderr.write(HOME_NOT_SET_STDERR_MESSAGE);
+      process.exitCode = 1;
+      return;
+    }
+
+    const provider = parseOptionalProvider(args.provider);
+    if (args.provider !== undefined && provider === undefined) {
+      process.stderr.write(`Unknown provider: ${args.provider}\n`);
+      process.exitCode = 2;
+      return;
+    }
+
+    const setupConfig = yield* readSetupConfig(home);
+    if (!isRestoreOnLaunchEnabled(setupConfig) && args.execArgv.length === 0) {
+      // Allow explicit watch even if disabled when following a child; wrappers enable lifecycle first.
+    }
+
+    const vaultPath = args.vaultPath ?? setupConfig?.vaultPath ?? resolveDefaultVaultPath(home);
+    const pollIntervalMs = parsePollMs(args.pollMs);
+    const compression = args.compression ?? createZstdCompression();
+    const json = args.json === true;
+
+    let childExitCode: number | undefined;
+    let stop = false;
+
+    if (args.execArgv.length > 0) {
+      const [command, ...commandArgs] = args.execArgv;
+      if (command === undefined) {
+        process.stderr.write('Missing command after -- for watch --exec.\n');
+        process.exitCode = 2;
+        return;
+      }
+
+      const child = spawn(command, commandArgs, {
+        stdio: 'inherit',
+        env: process.env,
+      });
+
+      child.on('exit', (code) => {
+        childExitCode = code ?? 0;
+        stop = true;
+      });
+    } else {
+      const onSignal = (): void => {
+        stop = true;
+      };
+      process.once('SIGINT', onSignal);
+      process.once('SIGTERM', onSignal);
+    }
+
+    const onEvent = (event: SessionWatchEvent): void => {
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ command: 'watch', ...event })}\n`);
+        return;
+      }
+
+      process.stderr.write(`watch: ${event.provider}/${event.sessionId} → ${event.status}\n`);
+    };
+
+    if (!json && args.execArgv.length === 0) {
+      process.stderr.write(
+        `watch: monitoring stubs under vault ${vaultPath}${provider === undefined ? '' : ` for ${provider}`} (Ctrl+C to stop)\n`,
+      );
+    }
+
+    yield* watchSessionStubs({
+      vaultPath,
+      provider,
+      compression,
+      pollIntervalMs,
+      shouldStop: () => stop,
+      onEvent,
+    });
+
+    if (childExitCode !== undefined) {
+      process.exitCode = childExitCode === 0 ? undefined : childExitCode;
+    }
+  });
+
+const extractExecArgs = (rawArgs: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const separator = rawArgs.indexOf('--');
+  if (separator === -1) {
+    return [];
+  }
+
+  return rawArgs.slice(separator + 1);
+};
+
+const parseOptionalProvider = (provider: string | undefined): ProviderId | undefined => {
+  if (provider === undefined) {
+    return undefined;
+  }
+
+  const decoded = Schema.decodeUnknownEither(ProviderIdSchema)(provider);
+  if (decoded._tag === 'Left') {
+    return undefined;
+  }
+
+  return decoded.right;
+};
+
+const parsePollMs = (value: string | undefined): number => {
+  if (value === undefined) {
+    return 750;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 100) {
+    return 750;
+  }
+
+  return Math.floor(parsed);
+};

src/cli/main.ts

@@ -14,6 +14,7 @@ import { restoreCommand } from './commands/restoreCommand.js';
 import { checkCommand, savingsCommand } from './commands/savingsCommand.js';
 import { scanCommand } from './commands/scanCommand.js';
 import { unpackCommand } from './commands/unpackCommand.js';
+import { watchCommand } from './commands/watchCommand.js';
 import { runInteractiveCli, shouldRunInteractiveCli } from './interactiveCli.js';
 import { rewriteCommandFlagAliases } from './mainArgs.js';
 import { isCliEntrypoint } from './mainEntrypoint.js';
@@ -39,6 +40,7 @@ export const mainCommand = defineCommand({
     restore: restoreCommand,
     open: openCommand,
     preflight: preflightCommand,
+    watch: watchCommand,
     maintain: maintainCommand,
     'ensure-restored': ensureRestoredCommand,
     lifecycle: lifecycleCommand,

src/cli/mainArgs.ts

@@ -10,6 +10,7 @@ const COMMAND_FLAG_ALIASES: Readonly<Record<string, string>> = {
   '--pack': 'pack',
   '--preflight': 'preflight',
   '--restore': 'restore',
+  '--watch': 'watch',
   '--savings': 'savings',
   '--scan': 'scan',
   '--unpack': 'unpack',

src/core/lifecycleWrappers.ts

@@ -160,6 +160,11 @@ if command -v node >/dev/null 2>&1; then
   node "$CLI_ENTRY" preflight --provider "$PROVIDER" -- "$@" >/dev/null 2>&1 || true
 fi
 
+# Follow the provider process and materialize GUI-opened stubs (no session id in argv).
+if command -v node >/dev/null 2>&1; then
+  exec node "$CLI_ENTRY" watch --provider "$PROVIDER" -- "$REAL_BIN" "$@"
+fi
+
 exec "$REAL_BIN" "$@"
 `;
 

src/core/sessionArchive.test.ts

@@ -347,7 +347,11 @@ describe('sessionArchive dry-run and status paths', () => {
         touchedOriginals: true,
       }),
     ]);
-    await expect(stat(session.path)).rejects.toMatchObject({ code: 'ENOENT' });
+    // Packed path keeps a listable stub so GUIs can still see the session.
+    const stubAfterPack = JSON.parse(await readFile(session.path, 'utf8')) as {
+      agentSessionPack: string;
+    };
+    expect(stubAfterPack.agentSessionPack).toBe('agent-session-pack-archived-stub');
 
     const unpackReport = await Effect.runPromise(
       unpackProviderSessions({
@@ -434,7 +438,10 @@ describe('sessionArchive dry-run and status paths', () => {
         compression: copyCompression,
       }),
     );
-    await expect(stat(session.path)).rejects.toMatchObject({ code: 'ENOENT' });
+    const stubAfterPack = JSON.parse(await readFile(session.path, 'utf8')) as {
+      agentSessionPack: string;
+    };
+    expect(stubAfterPack.agentSessionPack).toBe('agent-session-pack-archived-stub');
 
     const disabled = await Effect.runPromise(
       ensureSessionRestored({
@@ -448,7 +455,9 @@ describe('sessionArchive dry-run and status paths', () => {
       }),
     );
     expect(disabled.status).toBe('lifecycle-disabled');
-    await expect(stat(session.path)).rejects.toMatchObject({ code: 'ENOENT' });
+    await expect(readFile(session.path, 'utf8')).resolves.toContain(
+      'agent-session-pack-archived-stub',
+    );
 
     const restored = await Effect.runPromise(
       ensureSessionRestored({