@web-auto/camo 0.1.4 → 0.1.6

package/README.md

@@ -33,8 +33,11 @@ camo profile create myprofile
 # Set as default
 camo profile default myprofile
 
-# Start browser
-camo start --url https://example.com
+# Start browser (with alias)
+camo start --url https://example.com --alias main
+
+# Start headless worker (auto-kill after idle timeout)
+camo start worker-1 --headless --alias shard1 --idle-timeout 30m
 
 # Navigate
 camo goto https://www.xiaohongshu.com
@@ -68,15 +71,25 @@ camo create fingerprint --os <os> --region <region>
 ### Browser Control
 
 ```bash
-camo start [profileId] [--url <url>] [--headless]
+camo start [profileId] [--url <url>] [--headless] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
 camo stop [profileId]
+camo stop --id <instanceId>
+camo stop --alias <alias>
+camo stop idle
+camo stop all
 camo status [profileId]
 camo shutdown                          # Shutdown browser-service (all sessions)
 ```
 
+`camo start` in headful mode now persists window size per profile and reuses that size on next start.  
+If no saved size exists, it defaults to near-fullscreen (full width, slight vertical reserve).  
+Use `--width/--height` to override and update the saved profile size.
+For headless sessions, default idle timeout is `30m` (auto-stop on inactivity). Use `--idle-timeout` (e.g. `45m`, `1800s`, `0`) to customize.
+
 ### Lifecycle & Cleanup
 
 ```bash
+camo instances                         # List global camoufox instances (live + orphaned + idle state)
 camo sessions                          # List active browser sessions
 camo cleanup [profileId]               # Cleanup session (release lock + stop)
 camo cleanup all                       # Cleanup all active sessions
@@ -328,7 +341,7 @@ Condition types:
 Camo CLI persists session information locally:
 
 - Sessions are registered in `~/.webauto/sessions/`
-- On restart, `camo sessions` shows both live and orphaned sessions
+- On restart, `camo sessions` / `camo instances` shows live + orphaned sessions
 - Use `camo recover <profileId>` to reconnect or cleanup orphaned sessions
 - Stale sessions (>7 days) are automatically cleaned up
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/camo",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Camoufox Browser CLI - Cross-platform browser automation",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -2,7 +2,6 @@
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { listProfiles, getDefaultProfile, loadConfig, hasStartScript, setRepoRoot } from './utils/config.mjs';
-import { ensureCamoufox, ensureBrowserService } from './utils/browser-service.mjs';
 import { printHelp, printProfilesAndHint } from './utils/help.mjs';
 import { handleProfileCommand } from './commands/profile.mjs';
 import { handleInitCommand } from './commands/init.mjs';
@@ -24,7 +23,7 @@ import {
 } from './commands/browser.mjs';
 import {
   handleCleanupCommand, handleForceStopCommand, handleLockCommand,
- handleUnlockCommand, handleSessionsCommand
+ handleUnlockCommand, handleSessionsCommand, handleInstancesCommand
 } from './commands/lifecycle.mjs';
 import { handleSessionWatchdogCommand } from './lifecycle/session-watchdog.mjs';
 import { safeAppendProgressEvent } from './events/progress-log.mjs';
@@ -55,6 +54,13 @@ function inferProfileId(cmd, args) {
     'new-page', 'close-page', 'switch-page', 'list-pages',
     'cleanup', 'force-stop', 'lock', 'unlock', 'sessions',
   ].includes(cmd)) {
+    if ((cmd === 'stop' || cmd === 'close') && (args.includes('--id') || args.includes('--alias'))) {
+      return null;
+    }
+    const first = positionals[0] || null;
+    if ((cmd === 'stop' || cmd === 'close') && (first === 'all' || first === 'idle')) {
+      return null;
+    }
     return positionals[0] || null;
   }
 
@@ -212,6 +218,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'instances') {
+    await runTrackedCommand(cmd, args, () => handleInstancesCommand(args));
+    return;
+  }
+
   if (cmd === 'container') {
     await runTrackedCommand(cmd, args, () => handleContainerCommand(args));
     return;

package/src/commands/browser.mjs

@@ -1,11 +1,238 @@
 import fs from 'node:fs';
-import { listProfiles, getDefaultProfile } from '../utils/config.mjs';
+import {
+  listProfiles,
+  getDefaultProfile,
+  getProfileWindowSize,
+  setProfileWindowSize,
+} from '../utils/config.mjs';
 import { callAPI, ensureCamoufox, ensureBrowserService, getSessionByProfile, checkBrowserService } from '../utils/browser-service.mjs';
 import { resolveProfileId, ensureUrlScheme, looksLikeUrlToken, getPositionals } from '../utils/args.mjs';
-import { acquireLock, releaseLock, isLocked, getLockInfo, cleanupStaleLocks } from '../lifecycle/lock.mjs';
-import { registerSession, updateSession, getSessionInfo, unregisterSession, listRegisteredSessions, markSessionClosed, cleanupStaleSessions, recoverSession } from '../lifecycle/session-registry.mjs';
+import { acquireLock, releaseLock, cleanupStaleLocks } from '../lifecycle/lock.mjs';
+import {
+  registerSession,
+  updateSession,
+  getSessionInfo,
+  unregisterSession,
+  listRegisteredSessions,
+  markSessionClosed,
+  cleanupStaleSessions,
+  resolveSessionTarget,
+  isSessionAliasTaken,
+} from '../lifecycle/session-registry.mjs';
 import { startSessionWatchdog, stopAllSessionWatchdogs, stopSessionWatchdog } from '../lifecycle/session-watchdog.mjs';
 
+const START_WINDOW_MIN_WIDTH = 960;
+const START_WINDOW_MIN_HEIGHT = 700;
+const START_WINDOW_MAX_RESERVE = 240;
+const START_WINDOW_DEFAULT_RESERVE = 72;
+const DEFAULT_HEADLESS_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseNumber(value, fallback = 0) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function readFlagValue(args, names) {
+  for (let i = 0; i < args.length; i += 1) {
+    if (!names.includes(args[i])) continue;
+    const value = args[i + 1];
+    if (!value || String(value).startsWith('-')) return null;
+    return value;
+  }
+  return null;
+}
+
+function parseDurationMs(raw, fallbackMs) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return fallbackMs;
+  const text = String(raw).trim().toLowerCase();
+  if (text === '0' || text === 'off' || text === 'none' || text === 'disable' || text === 'disabled') return 0;
+  const matched = text.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (!matched) {
+    throw new Error('Invalid --idle-timeout. Use forms like 30m, 1800s, 5000ms, 1h, 0');
+  }
+  const value = Number(matched[1]);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error('Invalid --idle-timeout value');
+  }
+  const unit = matched[2] || 'm';
+  const factor = unit === 'h' ? 3600000 : unit === 'm' ? 60000 : unit === 's' ? 1000 : 1;
+  return Math.floor(value * factor);
+}
+
+function validateAlias(alias) {
+  const text = String(alias || '').trim();
+  if (!text) return null;
+  if (!/^[a-zA-Z0-9._-]+$/.test(text)) {
+    throw new Error('Invalid --alias. Use only letters, numbers, dot, underscore, dash.');
+  }
+  return text.slice(0, 64);
+}
+
+function formatDurationMs(ms) {
+  const value = Number(ms);
+  if (!Number.isFinite(value) || value <= 0) return 'disabled';
+  if (value % 3600000 === 0) return `${value / 3600000}h`;
+  if (value % 60000 === 0) return `${value / 60000}m`;
+  if (value % 1000 === 0) return `${value / 1000}s`;
+  return `${value}ms`;
+}
+
+function computeIdleState(session, now = Date.now()) {
+  const headless = session?.headless === true;
+  const timeoutMs = headless
+    ? (Number.isFinite(Number(session?.idleTimeoutMs)) ? Math.max(0, Number(session.idleTimeoutMs)) : DEFAULT_HEADLESS_IDLE_TIMEOUT_MS)
+    : 0;
+  const lastAt = Number(session?.lastActivityAt || session?.lastSeen || session?.startTime || now);
+  const idleMs = Math.max(0, now - (Number.isFinite(lastAt) ? lastAt : now));
+  const idle = headless && timeoutMs > 0 && idleMs >= timeoutMs;
+  return { headless, timeoutMs, idleMs, idle };
+}
+
+async function stopAndCleanupProfile(profileId, options = {}) {
+  const id = String(profileId || '').trim();
+  if (!id) return { profileId: id, ok: false, error: 'profile_required' };
+  const force = options.force === true;
+  const serviceUp = options.serviceUp === true;
+  let result = null;
+  let error = null;
+  if (serviceUp) {
+    try {
+      result = await callAPI('stop', force ? { profileId: id, force: true } : { profileId: id });
+    } catch (err) {
+      error = err;
+    }
+  }
+  stopSessionWatchdog(id);
+  releaseLock(id);
+  markSessionClosed(id);
+  return {
+    profileId: id,
+    ok: !error,
+    serviceUp,
+    result,
+    error: error ? (error.message || String(error)) : null,
+  };
+}
+
+export function computeTargetViewportFromWindowMetrics(measured) {
+  const innerWidth = Math.max(320, parseNumber(measured?.innerWidth, 0));
+  const innerHeight = Math.max(240, parseNumber(measured?.innerHeight, 0));
+  const outerWidth = Math.max(320, parseNumber(measured?.outerWidth, innerWidth));
+  const outerHeight = Math.max(240, parseNumber(measured?.outerHeight, innerHeight));
+
+  const rawDeltaW = Math.max(0, outerWidth - innerWidth);
+  const rawDeltaH = Math.max(0, outerHeight - innerHeight);
+  const frameW = rawDeltaW > 400 ? 16 : Math.min(rawDeltaW, 120);
+  const frameH = rawDeltaH > 400 ? 88 : Math.min(rawDeltaH, 180);
+
+  return {
+    width: Math.max(320, outerWidth - frameW),
+    height: Math.max(240, outerHeight - frameH),
+    frameW,
+    frameH,
+    innerWidth,
+    innerHeight,
+    outerWidth,
+    outerHeight,
+  };
+}
+
+export function computeStartWindowSize(metrics, options = {}) {
+  const display = metrics?.metrics || metrics || {};
+  const reserveFromEnv = parseNumber(process.env.CAMO_DEFAULT_WINDOW_VERTICAL_RESERVE, START_WINDOW_DEFAULT_RESERVE);
+  const reserve = clamp(
+    parseNumber(options.reservePx, reserveFromEnv),
+    0,
+    START_WINDOW_MAX_RESERVE,
+  );
+
+  const workWidth = parseNumber(display.workWidth, 0);
+  const workHeight = parseNumber(display.workHeight, 0);
+  const width = parseNumber(display.width, 0);
+  const height = parseNumber(display.height, 0);
+  const baseW = Math.floor(workWidth > 0 ? workWidth : width);
+  const baseH = Math.floor(workHeight > 0 ? workHeight : height);
+
+  if (baseW <= 0 || baseH <= 0) {
+    return {
+      width: 1920,
+      height: 1000,
+      reservePx: reserve,
+      source: 'fallback',
+    };
+  }
+
+  return {
+    width: Math.max(START_WINDOW_MIN_WIDTH, baseW),
+    height: Math.max(START_WINDOW_MIN_HEIGHT, baseH - reserve),
+    reservePx: reserve,
+    source: workWidth > 0 || workHeight > 0 ? 'workArea' : 'screen',
+  };
+}
+
+async function probeWindowMetrics(profileId) {
+  const measured = await callAPI('evaluate', {
+    profileId,
+    script: '({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, outerWidth: window.outerWidth, outerHeight: window.outerHeight })',
+  });
+  return measured?.result || {};
+}
+
+export async function syncWindowViewportAfterResize(profileId, width, height, options = {}) {
+  const settleMs = Math.max(40, parseNumber(options.settleMs, 120));
+  const attempts = Math.max(1, Math.min(8, Math.floor(parseNumber(options.attempts, 4))));
+  const tolerancePx = Math.max(0, parseNumber(options.tolerancePx, 3));
+
+  const windowResult = await callAPI('window:resize', { profileId, width, height });
+  await sleep(settleMs);
+
+  let measured = {};
+  let verified = {};
+  let viewport = null;
+  let matched = false;
+  let target = { width: 1280, height: 720, frameW: 16, frameH: 88 };
+
+  for (let i = 0; i < attempts; i += 1) {
+    measured = await probeWindowMetrics(profileId);
+    target = computeTargetViewportFromWindowMetrics(measured);
+    viewport = await callAPI('page:setViewport', {
+      profileId,
+      width: target.width,
+      height: target.height,
+    });
+    await sleep(settleMs);
+    verified = await probeWindowMetrics(profileId);
+    const dw = Math.abs(parseNumber(verified?.innerWidth, 0) - target.width);
+    const dh = Math.abs(parseNumber(verified?.innerHeight, 0) - target.height);
+    if (dw <= tolerancePx && dh <= tolerancePx) {
+      matched = true;
+      break;
+    }
+  }
+
+  return {
+    window: windowResult,
+    measured,
+    verified,
+    targetViewport: {
+      width: target.width,
+      height: target.height,
+      frameW: target.frameW,
+      frameH: target.frameH,
+      matched,
+    },
+    viewport,
+  };
+}
+
 export async function handleStartCommand(args) {
   ensureCamoufox();
   await ensureBrowserService();
@@ -14,6 +241,22 @@ export async function handleStartCommand(args) {
 
   const urlIdx = args.indexOf('--url');
   const explicitUrl = urlIdx >= 0 ? args[urlIdx + 1] : undefined;
+  const widthIdx = args.indexOf('--width');
+  const heightIdx = args.indexOf('--height');
+  const explicitWidth = widthIdx >= 0 ? parseNumber(args[widthIdx + 1], NaN) : NaN;
+  const explicitHeight = heightIdx >= 0 ? parseNumber(args[heightIdx + 1], NaN) : NaN;
+  const hasExplicitWidth = Number.isFinite(explicitWidth);
+  const hasExplicitHeight = Number.isFinite(explicitHeight);
+  const alias = validateAlias(readFlagValue(args, ['--alias']));
+  const idleTimeoutRaw = readFlagValue(args, ['--idle-timeout']);
+  const parsedIdleTimeoutMs = parseDurationMs(idleTimeoutRaw, DEFAULT_HEADLESS_IDLE_TIMEOUT_MS);
+  if (hasExplicitWidth !== hasExplicitHeight) {
+    throw new Error('Usage: camo start [profileId] [--url <url>] [--headless] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]');
+  }
+  if ((hasExplicitWidth && explicitWidth < START_WINDOW_MIN_WIDTH) || (hasExplicitHeight && explicitHeight < START_WINDOW_MIN_HEIGHT)) {
+    throw new Error(`Window size too small. Minimum is ${START_WINDOW_MIN_WIDTH}x${START_WINDOW_MIN_HEIGHT}`);
+  }
+  const hasExplicitWindowSize = hasExplicitWidth && hasExplicitHeight;
   const profileSet = new Set(listProfiles());
   let implicitUrl;
   
@@ -21,6 +264,8 @@ export async function handleStartCommand(args) {
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--url') { i++; continue; }
+    if (arg === '--width' || arg === '--height') { i++; continue; }
+    if (arg === '--alias' || arg === '--idle-timeout') { i++; continue; }
     if (arg === '--headless') continue;
     if (arg.startsWith('--')) continue;
 
@@ -39,23 +284,45 @@ export async function handleStartCommand(args) {
       throw new Error('No default profile set. Run: camo profile default <profileId>');
     }
   }
+  if (alias && isSessionAliasTaken(alias, profileId)) {
+    throw new Error(`Alias is already in use: ${alias}`);
+  }
 
   // Check for existing session in browser service
   const existing = await getSessionByProfile(profileId);
   if (existing) {
     // Session exists in browser service - update registry and lock
     acquireLock(profileId, { sessionId: existing.session_id || existing.profileId });
-    registerSession(profileId, {
-      sessionId: existing.session_id || existing.profileId,
-      url: existing.current_url,
-      mode: existing.mode,
-    });
+    const saved = getSessionInfo(profileId);
+    const record = saved
+      ? updateSession(profileId, {
+        sessionId: existing.session_id || existing.profileId,
+        url: existing.current_url,
+        mode: existing.mode,
+        alias: alias || saved.alias || null,
+      })
+      : registerSession(profileId, {
+        sessionId: existing.session_id || existing.profileId,
+        url: existing.current_url,
+        mode: existing.mode,
+        alias: alias || null,
+      });
+    const idleState = computeIdleState(record);
     console.log(JSON.stringify({
       ok: true,
       sessionId: existing.session_id || existing.profileId,
+      instanceId: record.instanceId,
       profileId,
       message: 'Session already running',
       url: existing.current_url,
+      alias: record.alias || null,
+      idleTimeoutMs: idleState.timeoutMs,
+      idleTimeout: formatDurationMs(idleState.timeoutMs),
+      closeHint: {
+        byProfile: `camo stop ${profileId}`,
+        byId: `camo stop --id ${record.instanceId}`,
+        byAlias: record.alias ? `camo stop --alias ${record.alias}` : null,
+      },
     }, null, 2));
     startSessionWatchdog(profileId);
     return;
@@ -71,6 +338,7 @@ export async function handleStartCommand(args) {
   }
 
   const headless = args.includes('--headless');
+  const idleTimeoutMs = headless ? parsedIdleTimeoutMs : 0;
   const targetUrl = explicitUrl || implicitUrl;
   const result = await callAPI('start', {
     profileId,
@@ -81,35 +349,188 @@ export async function handleStartCommand(args) {
   if (result?.ok) {
     const sessionId = result.sessionId || result.profileId || profileId;
     acquireLock(profileId, { sessionId });
-    registerSession(profileId, {
+    const record = registerSession(profileId, {
       sessionId,
       url: targetUrl,
       headless,
+      alias,
+      idleTimeoutMs,
+      lastAction: 'start',
     });
     startSessionWatchdog(profileId);
+    result.instanceId = record.instanceId;
+    result.alias = record.alias || null;
+    result.idleTimeoutMs = idleTimeoutMs;
+    result.idleTimeout = formatDurationMs(idleTimeoutMs);
+    result.closeHint = {
+      byProfile: `camo stop ${profileId}`,
+      byId: `camo stop --id ${record.instanceId}`,
+      byAlias: record.alias ? `camo stop --alias ${record.alias}` : null,
+      all: 'camo close all',
+    };
+    result.message = headless
+      ? `Started headless session. Idle timeout: ${formatDurationMs(idleTimeoutMs)}`
+      : 'Started session. Remember to stop it when finished.';
+
+    if (!headless) {
+      let windowTarget = null;
+      if (hasExplicitWindowSize) {
+        windowTarget = {
+          width: Math.floor(explicitWidth),
+          height: Math.floor(explicitHeight),
+          source: 'explicit',
+        };
+      } else {
+        const rememberedWindow = getProfileWindowSize(profileId);
+        if (rememberedWindow) {
+          windowTarget = {
+            width: rememberedWindow.width,
+            height: rememberedWindow.height,
+            source: 'profile',
+            updatedAt: rememberedWindow.updatedAt,
+          };
+        } else {
+          const display = await callAPI('system:display', {}).catch(() => null);
+          windowTarget = computeStartWindowSize(display);
+        }
+      }
+
+      result.startWindow = {
+        width: windowTarget.width,
+        height: windowTarget.height,
+        source: windowTarget.source,
+      };
+
+      const syncResult = await syncWindowViewportAfterResize(
+        profileId,
+        windowTarget.width,
+        windowTarget.height,
+      ).catch((err) => ({ error: err?.message || String(err) }));
+      result.windowSync = syncResult;
+
+      const measuredOuterWidth = Number(syncResult?.verified?.outerWidth);
+      const measuredOuterHeight = Number(syncResult?.verified?.outerHeight);
+      const savedWindow = setProfileWindowSize(
+        profileId,
+        Number.isFinite(measuredOuterWidth) ? measuredOuterWidth : windowTarget.width,
+        Number.isFinite(measuredOuterHeight) ? measuredOuterHeight : windowTarget.height,
+      );
+      result.profileWindow = savedWindow?.window || null;
+    }
   }
   console.log(JSON.stringify(result, null, 2));
 }
 
 export async function handleStopCommand(args) {
-  await ensureBrowserService();
-  const profileId = resolveProfileId(args, 1, getDefaultProfile);
-  if (!profileId) throw new Error('Usage: camo stop [profileId]');
+  const rawTarget = String(args[1] || '').trim();
+  const target = rawTarget.toLowerCase();
+  const idTarget = readFlagValue(args, ['--id']);
+  const aliasTarget = readFlagValue(args, ['--alias']);
+  const stopIdle = target === 'idle' || args.includes('--idle');
+  const stopAll = target === 'all';
+  const serviceUp = await checkBrowserService();
 
-  let result = null;
-  let stopError = null;
-  try {
-    result = await callAPI('stop', { profileId });
-  } catch (err) {
-    stopError = err;
-  } finally {
-    stopSessionWatchdog(profileId);
-    releaseLock(profileId);
-    markSessionClosed(profileId);
+  if (stopAll) {
+    let liveSessions = [];
+    if (serviceUp) {
+      try {
+        const status = await callAPI('getStatus', {});
+        liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
+      } catch {
+        // Ignore and fallback to local registry.
+      }
+    }
+    const profileSet = new Set(liveSessions.map((item) => String(item?.profileId || '').trim()).filter(Boolean));
+    for (const session of listRegisteredSessions()) {
+      if (String(session?.status || '').trim() === 'closed') continue;
+      const profileId = String(session?.profileId || '').trim();
+      if (profileId) profileSet.add(profileId);
+    }
+
+    const results = [];
+    for (const profileId of profileSet) {
+      // eslint-disable-next-line no-await-in-loop
+      results.push(await stopAndCleanupProfile(profileId, { serviceUp }));
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      mode: 'all',
+      serviceUp,
+      closed: results.filter((item) => item.ok).length,
+      failed: results.filter((item) => !item.ok).length,
+      results,
+    }, null, 2));
+    return;
   }
 
-  if (stopError) throw stopError;
-  console.log(JSON.stringify(result, null, 2));
+  if (stopIdle) {
+    const now = Date.now();
+    const idleTargets = listRegisteredSessions()
+      .filter((item) => String(item?.status || '').trim() === 'active')
+      .map((item) => ({ session: item, idle: computeIdleState(item, now) }))
+      .filter((item) => item.idle.idle)
+      .map((item) => item.session.profileId);
+    const results = [];
+    for (const profileId of idleTargets) {
+      // eslint-disable-next-line no-await-in-loop
+      results.push(await stopAndCleanupProfile(profileId, { serviceUp }));
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      mode: 'idle',
+      serviceUp,
+      targetCount: idleTargets.length,
+      closed: results.filter((item) => item.ok).length,
+      failed: results.filter((item) => !item.ok).length,
+      results,
+    }, null, 2));
+    return;
+  }
+
+  let profileId = null;
+  let resolvedBy = 'profile';
+  if (idTarget) {
+    const resolved = resolveSessionTarget(idTarget);
+    if (!resolved) throw new Error(`No session found for instance id: ${idTarget}`);
+    profileId = resolved.profileId;
+    resolvedBy = resolved.reason;
+  } else if (aliasTarget) {
+    const resolved = resolveSessionTarget(aliasTarget);
+    if (!resolved) throw new Error(`No session found for alias: ${aliasTarget}`);
+    profileId = resolved.profileId;
+    resolvedBy = resolved.reason;
+  } else {
+    const positional = args.slice(1).find((arg) => arg && !String(arg).startsWith('--')) || null;
+    if (positional) {
+      const resolved = resolveSessionTarget(positional);
+      if (resolved) {
+        profileId = resolved.profileId;
+        resolvedBy = resolved.reason;
+      } else {
+        profileId = positional;
+      }
+    }
+  }
+
+  if (!profileId) {
+    profileId = getDefaultProfile();
+  }
+  if (!profileId) {
+    throw new Error('Usage: camo stop [profileId] | camo stop --id <instanceId> | camo stop --alias <alias> | camo stop all | camo stop idle');
+  }
+
+  const result = await stopAndCleanupProfile(profileId, { serviceUp });
+  if (!result.ok && serviceUp) {
+    throw new Error(result.error || `stop failed for profile: ${profileId}`);
+  }
+  console.log(JSON.stringify({
+    ok: true,
+    profileId,
+    resolvedBy,
+    serviceUp,
+    warning: (!serviceUp && !result.ok) ? result.error : null,
+    result: result.result || null,
+  }, null, 2));
 }
 
 export async function handleStatusCommand(args) {

package/src/commands/lifecycle.mjs

@@ -5,13 +5,81 @@
 import { getDefaultProfile } from '../utils/config.mjs';
 import { callAPI, ensureBrowserService, checkBrowserService } from '../utils/browser-service.mjs';
 import { resolveProfileId } from '../utils/args.mjs';
-import { acquireLock, getLockInfo, releaseLock, isLocked, cleanupStaleLocks, listActiveLocks } from '../lifecycle/lock.mjs';
+import { acquireLock, getLockInfo, releaseLock, cleanupStaleLocks, listActiveLocks } from '../lifecycle/lock.mjs';
 import { 
   getSessionInfo, unregisterSession, markSessionClosed, cleanupStaleSessions,
-  listRegisteredSessions, registerSession, updateSession
+  listRegisteredSessions, updateSession
 } from '../lifecycle/session-registry.mjs';
 import { stopAllSessionWatchdogs, stopSessionWatchdog } from '../lifecycle/session-watchdog.mjs';
 
+const DEFAULT_HEADLESS_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+
+function computeIdleState(session, now = Date.now()) {
+  const headless = session?.headless === true;
+  const timeoutMs = headless
+    ? (Number.isFinite(Number(session?.idleTimeoutMs)) ? Math.max(0, Number(session.idleTimeoutMs)) : DEFAULT_HEADLESS_IDLE_TIMEOUT_MS)
+    : 0;
+  const lastAt = Number(session?.lastActivityAt || session?.lastSeen || session?.startTime || now);
+  const idleMs = Math.max(0, now - (Number.isFinite(lastAt) ? lastAt : now));
+  const idle = headless && timeoutMs > 0 && idleMs >= timeoutMs;
+  return { headless, timeoutMs, idleMs, idle };
+}
+
+function buildMergedSessionRows(liveSessions, registeredSessions) {
+  const now = Date.now();
+  const regMap = new Map(registeredSessions.map((item) => [item.profileId, item]));
+  const rows = [];
+  const liveMap = new Map(liveSessions.map((item) => [item.profileId, item]));
+
+  for (const live of liveSessions) {
+    const reg = regMap.get(live.profileId);
+    const idle = computeIdleState(reg || {}, now);
+    rows.push({
+      profileId: live.profileId,
+      sessionId: live.session_id || live.profileId,
+      instanceId: reg?.instanceId || live.session_id || live.profileId,
+      alias: reg?.alias || null,
+      url: live.current_url,
+      mode: live.mode,
+      headless: idle.headless,
+      idleTimeoutMs: idle.timeoutMs,
+      idleMs: idle.idleMs,
+      idle: idle.idle,
+      live: true,
+      registered: !!reg,
+      registryStatus: reg?.status,
+      lastSeen: reg?.lastSeen || null,
+      lastActivityAt: reg?.lastActivityAt || null,
+    });
+  }
+
+  for (const reg of registeredSessions) {
+    if (liveMap.has(reg.profileId)) continue;
+    if (reg.status === 'closed') continue;
+    const idle = computeIdleState(reg, now);
+    rows.push({
+      profileId: reg.profileId,
+      sessionId: reg.sessionId || reg.profileId,
+      instanceId: reg.instanceId || reg.sessionId || reg.profileId,
+      alias: reg.alias || null,
+      url: reg.url || null,
+      mode: reg.mode || null,
+      headless: idle.headless,
+      idleTimeoutMs: idle.timeoutMs,
+      idleMs: idle.idleMs,
+      idle: idle.idle,
+      live: false,
+      orphaned: true,
+      needsRecovery: reg.status === 'active',
+      registered: true,
+      registryStatus: reg.status,
+      lastSeen: reg.lastSeen || null,
+      lastActivityAt: reg.lastActivityAt || null,
+    });
+  }
+  return rows;
+}
+
 export async function handleCleanupCommand(args) {
   const sub = args[1];
   
@@ -158,38 +226,7 @@ export async function handleSessionsCommand(args) {
     } catch {}
   }
   
-  // Build a map of live sessions
-  const liveMap = new Map(liveSessions.map(s => [s.profileId, s]));
-  
-  // Merge live and registered sessions
-  const merged = [];
-  
-  // Add all live sessions
-  for (const live of liveSessions) {
-    const reg = getSessionInfo(live.profileId);
-    merged.push({
-      profileId: live.profileId,
-      sessionId: live.session_id || live.profileId,
-      url: live.current_url,
-      mode: live.mode,
-      live: true,
-      registered: !!reg,
-      registryStatus: reg?.status,
-      lastSeen: reg?.lastSeen,
-    });
-  }
-  
-  // Add registered sessions that are not live (orphaned)
-  for (const reg of registeredSessions) {
-    if (!liveMap.has(reg.profileId) && reg.status !== 'closed') {
-      merged.push({
-        ...reg,
-        live: false,
-        orphaned: true,
-        needsRecovery: reg.status === 'active',
-      });
-    }
-  }
+  const merged = buildMergedSessionRows(liveSessions, registeredSessions);
   
   console.log(JSON.stringify({
     ok: true,
@@ -202,6 +239,10 @@ export async function handleSessionsCommand(args) {
   }, null, 2));
 }
 
+export async function handleInstancesCommand(args) {
+  await handleSessionsCommand(args);
+}
+
 export async function handleRecoverCommand(args) {
   const profileId = resolveProfileId(args, 1, getDefaultProfile);
   if (!profileId) throw new Error('Usage: camo recover [profileId]');

package/src/commands/window.mjs

@@ -1,7 +1,38 @@
-import { getDefaultProfile } from '../utils/config.mjs';
+import { getDefaultProfile, setProfileWindowSize } from '../utils/config.mjs';
 import { callAPI, ensureBrowserService } from '../utils/browser-service.mjs';
 import { getPositionals } from '../utils/args.mjs';
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function computeTargetViewport(measured) {
+  const innerWidth = Math.max(320, Number(measured?.innerWidth || 0) || 0);
+  const innerHeight = Math.max(240, Number(measured?.innerHeight || 0) || 0);
+  const outerWidth = Math.max(320, Number(measured?.outerWidth || 0) || innerWidth);
+  const outerHeight = Math.max(240, Number(measured?.outerHeight || 0) || innerHeight);
+
+  const rawDeltaW = Math.max(0, outerWidth - innerWidth);
+  const rawDeltaH = Math.max(0, outerHeight - innerHeight);
+  const frameW = rawDeltaW > 400 ? 16 : Math.min(rawDeltaW, 120);
+  const frameH = rawDeltaH > 400 ? 88 : Math.min(rawDeltaH, 180);
+
+  return {
+    width: Math.max(320, outerWidth - frameW),
+    height: Math.max(240, outerHeight - frameH),
+    frameW,
+    frameH,
+  };
+}
+
+async function probeWindowMetrics(profileId) {
+  const measured = await callAPI('evaluate', {
+    profileId,
+    script: '({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, outerWidth: window.outerWidth, outerHeight: window.outerHeight })',
+  });
+  return measured?.result || {};
+}
+
 export async function handleWindowCommand(args) {
   await ensureBrowserService();
 
@@ -24,36 +55,66 @@ export async function handleWindowCommand(args) {
     const width = parseInt(args[widthIdx + 1]);
     const height = parseInt(args[heightIdx + 1]);
     const result = await callAPI('window:resize', { profileId, width, height });
-    const measured = await callAPI('evaluate', {
-      profileId,
-      script: '({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, outerWidth: window.outerWidth, outerHeight: window.outerHeight })',
-    });
-    const innerWidth = Math.max(320, Number(measured?.result?.innerWidth || 0) || 0);
-    const innerHeight = Math.max(240, Number(measured?.result?.innerHeight || 0) || 0);
-    const outerWidth = Math.max(320, Number(measured?.result?.outerWidth || 0) || innerWidth);
-    const outerHeight = Math.max(240, Number(measured?.result?.outerHeight || 0) || innerHeight);
-    const rawDeltaW = Math.max(0, outerWidth - innerWidth);
-    const rawDeltaH = Math.max(0, outerHeight - innerHeight);
-    const frameW = rawDeltaW > 400 ? 16 : Math.min(rawDeltaW, 120);
-    const frameH = rawDeltaH > 400 ? 88 : Math.min(rawDeltaH, 180);
-    const targetViewportWidth = Math.max(320, outerWidth - frameW);
-    const targetViewportHeight = Math.max(240, outerHeight - frameH);
-    const viewport = await callAPI('page:setViewport', {
+
+    const attempts = 4;
+    const settleMs = 120;
+    const tolerancePx = 3;
+    let measured = {};
+    let verified = {};
+    let viewport = null;
+    let targetViewportWidth = 1280;
+    let targetViewportHeight = 720;
+    let frameW = 16;
+    let frameH = 88;
+    let matched = false;
+
+    await sleep(settleMs);
+    for (let i = 0; i < attempts; i += 1) {
+      measured = await probeWindowMetrics(profileId);
+      const target = computeTargetViewport(measured);
+      targetViewportWidth = target.width;
+      targetViewportHeight = target.height;
+      frameW = target.frameW;
+      frameH = target.frameH;
+
+      viewport = await callAPI('page:setViewport', {
+        profileId,
+        width: targetViewportWidth,
+        height: targetViewportHeight,
+      });
+
+      await sleep(settleMs);
+      verified = await probeWindowMetrics(profileId);
+      const dw = Math.abs((Number(verified?.innerWidth || 0)) - targetViewportWidth);
+      const dh = Math.abs((Number(verified?.innerHeight || 0)) - targetViewportHeight);
+      if (dw <= tolerancePx && dh <= tolerancePx) {
+        matched = true;
+        break;
+      }
+    }
+
+    const measuredOuterWidth = Number(verified?.outerWidth);
+    const measuredOuterHeight = Number(verified?.outerHeight);
+    const savedWindow = setProfileWindowSize(
       profileId,
-      width: targetViewportWidth,
-      height: targetViewportHeight,
-    });
+      Number.isFinite(measuredOuterWidth) ? measuredOuterWidth : width,
+      Number.isFinite(measuredOuterHeight) ? measuredOuterHeight : height,
+    );
+
     console.log(JSON.stringify({
       ok: true,
       profileId,
       window: result,
-      measured: measured?.result || null,
+      measured: measured || null,
+      verified: verified || null,
       targetViewport: {
         width: targetViewportWidth,
         height: targetViewportHeight,
         frameW,
         frameH,
+        matched,
       },
+      profileWindow: savedWindow?.window || null,
       viewport,
     }, null, 2));
   } else {

package/src/lifecycle/session-registry.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
 
 const SESSION_DIR = path.join(os.homedir(), '.webauto', 'sessions');
 
@@ -15,6 +16,25 @@ function ensureSessionDir() {
   }
 }
 
+function normalizeAlias(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  if (!/^[a-zA-Z0-9._-]+$/.test(text)) {
+    throw new Error('Invalid alias. Use only letters, numbers, dot, underscore, dash.');
+  }
+  return text.slice(0, 64);
+}
+
+function normalizeTimeoutMs(value) {
+  const ms = Number(value);
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  return Math.floor(ms);
+}
+
+function generateInstanceId() {
+  return `inst_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+}
+
 export function getSessionFile(profileId) {
   return path.join(SESSION_DIR, `${profileId}.json`);
 }
@@ -22,14 +42,24 @@ export function getSessionFile(profileId) {
 export function registerSession(profileId, sessionInfo = {}) {
   ensureSessionDir();
   const sessionFile = getSessionFile(profileId);
+  const now = Date.now();
+  const alias = normalizeAlias(sessionInfo.alias);
+  const idleTimeoutMs = normalizeTimeoutMs(sessionInfo.idleTimeoutMs);
+  const instanceId = String(sessionInfo.instanceId || sessionInfo.sessionId || generateInstanceId()).trim();
   
   const sessionData = {
     profileId,
     pid: process.pid,
-    startTime: Date.now(),
-    lastSeen: Date.now(),
+    instanceId,
+    alias,
+    startTime: now,
+    lastSeen: now,
+    lastActivityAt: now,
     status: 'active',
     ...sessionInfo,
+    instanceId,
+    alias,
+    idleTimeoutMs,
   };
   
   fs.writeFileSync(sessionFile, JSON.stringify(sessionData, null, 2));
@@ -44,12 +74,30 @@ export function updateSession(profileId, updates = {}) {
   
   try {
     const existing = JSON.parse(fs.readFileSync(sessionFile, 'utf-8'));
+    const now = Date.now();
+    const mergedAlias = Object.prototype.hasOwnProperty.call(updates, 'alias')
+      ? normalizeAlias(updates.alias)
+      : normalizeAlias(existing.alias);
+    const mergedIdleTimeoutMs = Object.prototype.hasOwnProperty.call(updates, 'idleTimeoutMs')
+      ? normalizeTimeoutMs(updates.idleTimeoutMs)
+      : normalizeTimeoutMs(existing.idleTimeoutMs);
+    const touchActivity = updates.touchActivity === true;
+    const nextActivityAt = touchActivity
+      ? now
+      : (Object.prototype.hasOwnProperty.call(updates, 'lastActivityAt')
+        ? Number(updates.lastActivityAt) || now
+        : Number(existing.lastActivityAt) || now);
     const updated = {
       ...existing,
       ...updates,
-      lastSeen: Date.now(),
+      instanceId: String(updates.instanceId || existing.instanceId || updates.sessionId || existing.sessionId || generateInstanceId()).trim(),
+      alias: mergedAlias,
+      idleTimeoutMs: mergedIdleTimeoutMs,
+      lastSeen: now,
+      lastActivityAt: nextActivityAt,
       profileId,
     };
+    delete updated.touchActivity;
     fs.writeFileSync(sessionFile, JSON.stringify(updated, null, 2));
     return updated;
   } catch {
@@ -93,6 +141,54 @@ export function listRegisteredSessions() {
   return sessions;
 }
 
+export function findSessionByAlias(alias) {
+  const target = normalizeAlias(alias);
+  if (!target) return null;
+  return listRegisteredSessions().find((item) => normalizeAlias(item?.alias) === target) || null;
+}
+
+export function findSessionByInstanceId(instanceId) {
+  const target = String(instanceId || '').trim();
+  if (!target) return null;
+  return listRegisteredSessions().find((item) => String(item?.instanceId || '').trim() === target) || null;
+}
+
+export function resolveSessionTarget(target) {
+  const value = String(target || '').trim();
+  if (!value) return null;
+  const sessions = listRegisteredSessions();
+  const byProfile = sessions.find((item) => String(item?.profileId || '').trim() === value);
+  if (byProfile) return { profileId: byProfile.profileId, reason: 'profile', session: byProfile };
+  const byInstanceId = sessions.find((item) => String(item?.instanceId || '').trim() === value);
+  if (byInstanceId) return { profileId: byInstanceId.profileId, reason: 'instanceId', session: byInstanceId };
+  const byAlias = sessions.find((item) => normalizeAlias(item?.alias) === normalizeAlias(value));
+  if (byAlias) return { profileId: byAlias.profileId, reason: 'alias', session: byAlias };
+  return null;
+}
+
+export function isSessionAliasTaken(alias, exceptProfileId = '') {
+  const target = normalizeAlias(alias);
+  if (!target) return false;
+  const except = String(exceptProfileId || '').trim();
+  return listRegisteredSessions().some((item) => {
+    if (!item) return false;
+    if (except && String(item.profileId || '').trim() === except) return false;
+    if (String(item.status || '').trim() !== 'active') return false;
+    return normalizeAlias(item.alias) === target;
+  });
+}
+
+export function touchSessionActivity(profileId, updates = {}) {
+  const id = String(profileId || '').trim();
+  if (!id) return null;
+  const existing = getSessionInfo(id);
+  if (!existing) return null;
+  return updateSession(id, {
+    ...updates,
+    touchActivity: true,
+  });
+}
+
 export function markSessionReconnecting(profileId) {
   return updateSession(profileId, { status: 'reconnecting', reconnectAttempt: Date.now() });
 }

package/src/lifecycle/session-watchdog.mjs

@@ -9,6 +9,7 @@ import { releaseLock } from './lock.mjs';
 import { getSessionInfo, markSessionClosed } from './session-registry.mjs';
 
 const WATCHDOG_DIR = path.join(os.homedir(), '.webauto', 'run', 'camo-watchdogs');
+const DEFAULT_HEADLESS_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
 function ensureWatchdogDir() {
   if (!fs.existsSync(WATCHDOG_DIR)) {
@@ -63,9 +64,50 @@ function isBlankUrl(url) {
   return text === '' || text === 'about:blank' || text === 'about:blank#blocked';
 }
 
-function shouldExitMonitor(profileId) {
-  const info = getSessionInfo(profileId);
-  return !info || info.status !== 'active';
+function computeTargetViewportFromWindow(measured) {
+  const innerWidth = Math.max(320, Number(measured?.innerWidth || 0) || 0);
+  const innerHeight = Math.max(240, Number(measured?.innerHeight || 0) || 0);
+  const outerWidth = Math.max(320, Number(measured?.outerWidth || 0) || innerWidth);
+  const outerHeight = Math.max(240, Number(measured?.outerHeight || 0) || innerHeight);
+  const rawDeltaW = Math.max(0, outerWidth - innerWidth);
+  const rawDeltaH = Math.max(0, outerHeight - innerHeight);
+  const frameW = rawDeltaW > 400 ? 16 : Math.min(rawDeltaW, 120);
+  const frameH = rawDeltaH > 400 ? 88 : Math.min(rawDeltaH, 180);
+  return {
+    width: Math.max(320, outerWidth - frameW),
+    height: Math.max(240, outerHeight - frameH),
+    innerWidth,
+    innerHeight,
+  };
+}
+
+async function probeWindowMetrics(profileId) {
+  const measured = await callAPI('evaluate', {
+    profileId,
+    script: '({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, outerWidth: window.outerWidth, outerHeight: window.outerHeight })',
+  });
+  return measured?.result || {};
+}
+
+async function syncViewportWithWindow(profileId, tolerancePx = 3) {
+  const measured = await probeWindowMetrics(profileId);
+  const target = computeTargetViewportFromWindow(measured);
+  const dw = Math.abs(target.innerWidth - target.width);
+  const dh = Math.abs(target.innerHeight - target.height);
+  if (dw <= tolerancePx && dh <= tolerancePx) return false;
+  await callAPI('page:setViewport', {
+    profileId,
+    width: target.width,
+    height: target.height,
+  });
+  return true;
+}
+
+function resolveIdleTimeoutMs(sessionInfo) {
+  if (!sessionInfo || sessionInfo.headless !== true) return 0;
+  const raw = Number(sessionInfo.idleTimeoutMs);
+  if (Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+  return DEFAULT_HEADLESS_IDLE_TIMEOUT_MS;
 }
 
 async function cleanupSession(profileId) {
@@ -78,6 +120,8 @@ async function runMonitor(profileId, options = {}) {
   const intervalMs = Math.max(500, Number(options.intervalMs) || 1200);
   const emptyThreshold = Math.max(1, Number(options.emptyThreshold) || 2);
   const blankThreshold = Math.max(1, Number(options.blankThreshold) || 3);
+  const viewportSyncIntervalMs = Math.max(500, Number(options.viewportSyncIntervalMs) || 1500);
+  let lastViewportSyncAt = 0;
 
   let seenAnyPage = false;
   let seenNonBlankPage = false;
@@ -85,7 +129,18 @@ async function runMonitor(profileId, options = {}) {
   let blankOnlyStreak = 0;
 
   while (true) {
-    if (shouldExitMonitor(profileId)) return;
+    const localInfo = getSessionInfo(profileId);
+    if (!localInfo || localInfo.status !== 'active') return;
+
+    const idleTimeoutMs = resolveIdleTimeoutMs(localInfo);
+    if (idleTimeoutMs > 0) {
+      const lastActivityAt = Number(localInfo.lastActivityAt || localInfo.lastSeen || localInfo.startTime || Date.now());
+      const idleMs = Date.now() - lastActivityAt;
+      if (idleMs >= idleTimeoutMs) {
+        await cleanupSession(profileId);
+        return;
+      }
+    }
 
     let sessions = [];
     try {
@@ -140,6 +195,12 @@ async function runMonitor(profileId, options = {}) {
       return;
     }
 
+    const now = Date.now();
+    if (pages.length > 0 && now - lastViewportSyncAt >= viewportSyncIntervalMs) {
+      lastViewportSyncAt = now;
+      await syncViewportWithWindow(profileId).catch(() => {});
+    }
+
     await sleep(intervalMs);
   }
 }

package/src/utils/browser-service.mjs

@@ -4,6 +4,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { BROWSER_SERVICE_URL, loadConfig, setRepoRoot } from './config.mjs';
+import { touchSessionActivity } from '../lifecycle/session-registry.mjs';
+
+function shouldTrackSessionActivity(action, payload) {
+  const profileId = String(payload?.profileId || '').trim();
+  if (!profileId) return false;
+  if (action === 'getStatus' || action === 'service:shutdown' || action === 'stop') return false;
+  return true;
+}
 
 export async function callAPI(action, payload = {}) {
   const r = await fetch(`${BROWSER_SERVICE_URL}/command`, {
@@ -21,6 +29,12 @@ export async function callAPI(action, payload = {}) {
   }
 
   if (!r.ok) throw new Error(body?.error || `HTTP ${r.status}`);
+  if (shouldTrackSessionActivity(action, payload)) {
+    touchSessionActivity(payload.profileId, {
+      lastAction: String(action || '').trim() || null,
+      lastActionAt: Date.now(),
+    });
+  }
   return body;
 }
 

package/src/utils/config.mjs

@@ -6,6 +6,7 @@ import os from 'node:os';
 export const CONFIG_DIR = path.join(os.homedir(), '.webauto');
 export const PROFILES_DIR = path.join(CONFIG_DIR, 'profiles');
 export const CONFIG_FILE = path.join(CONFIG_DIR, 'camo-cli.json');
+export const PROFILE_META_FILE = 'camo-profile.json';
 export const BROWSER_SERVICE_URL = process.env.WEBAUTO_BROWSER_URL || 'http://127.0.0.1:7704';
 
 export function ensureDir(p) {
@@ -55,13 +56,13 @@ export function createProfile(profileId) {
   if (!isValidProfileId(profileId)) {
     throw new Error('Invalid profileId. Use only letters, numbers, dot, underscore, dash.');
   }
-  const profileDir = path.join(PROFILES_DIR, profileId);
+  const profileDir = getProfileDir(profileId);
   if (fs.existsSync(profileDir)) throw new Error(`Profile already exists: ${profileId}`);
   ensureDir(profileDir);
 }
 
 export function deleteProfile(profileId) {
-  const profileDir = path.join(PROFILES_DIR, profileId);
+  const profileDir = getProfileDir(profileId);
   if (!fs.existsSync(profileDir)) throw new Error(`Profile not found: ${profileId}`);
   fs.rmSync(profileDir, { recursive: true, force: true });
 }
@@ -82,6 +83,61 @@ export function getDefaultProfile() {
   return loadConfig().defaultProfile;
 }
 
+export function getProfileDir(profileId) {
+  return path.join(PROFILES_DIR, String(profileId || '').trim());
+}
+
+export function getProfileMetaFile(profileId) {
+  return path.join(getProfileDir(profileId), PROFILE_META_FILE);
+}
+
+function loadProfileMeta(profileId) {
+  if (!isValidProfileId(profileId)) return {};
+  return readJson(getProfileMetaFile(profileId)) || {};
+}
+
+function saveProfileMeta(profileId, patch) {
+  if (!isValidProfileId(profileId)) return null;
+  const profileDir = getProfileDir(profileId);
+  ensureDir(profileDir);
+  const current = loadProfileMeta(profileId);
+  const next = {
+    ...current,
+    ...patch,
+    updatedAt: Date.now(),
+  };
+  writeJson(getProfileMetaFile(profileId), next);
+  return next;
+}
+
+export function getProfileWindowSize(profileId) {
+  const meta = loadProfileMeta(profileId);
+  const width = Number(meta?.window?.width);
+  const height = Number(meta?.window?.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  if (width < 320 || height < 240) return null;
+  return {
+    width: Math.floor(width),
+    height: Math.floor(height),
+    updatedAt: Number(meta?.window?.updatedAt) || Number(meta?.updatedAt) || null,
+  };
+}
+
+export function setProfileWindowSize(profileId, width, height) {
+  const parsedWidth = Number(width);
+  const parsedHeight = Number(height);
+  if (!Number.isFinite(parsedWidth) || !Number.isFinite(parsedHeight)) return null;
+  if (parsedWidth < 320 || parsedHeight < 240) return null;
+  const now = Date.now();
+  return saveProfileMeta(profileId, {
+    window: {
+      width: Math.floor(parsedWidth),
+      height: Math.floor(parsedHeight),
+      updatedAt: now,
+    },
+  });
+}
+
 const START_SCRIPT_REL = path.join('runtime', 'infra', 'utils', 'scripts', 'service', 'start-browser-service.mjs');
 
 export function hasStartScript(root) {

package/src/utils/help.mjs

@@ -24,12 +24,17 @@ CONFIG:
 
 BROWSER CONTROL:
   init                                      Ensure camoufox + ensure browser-service daemon
-  start [profileId] [--url <url>] [--headless]
+  start [profileId] [--url <url>] [--headless] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
   stop [profileId]
+  stop --id <instanceId>                    Stop by instance id
+  stop --alias <alias>                      Stop by alias
+  stop idle                                 Stop all idle sessions
+  stop all                                  Stop all sessions
   status [profileId]
   list                                      Alias of status
 
 LIFECYCLE & CLEANUP:
+  instances                                 List global camoufox instances (live + registered + idle state)
   sessions                                  List active browser sessions
   cleanup [profileId]                       Cleanup session (release lock + stop)
   cleanup all                               Cleanup all active sessions
@@ -90,7 +95,13 @@ EXAMPLES:
   camo create fingerprint --os windows --region uk
   camo profile create myprofile
   camo profile default myprofile
-  camo start --url https://example.com
+  camo start --url https://example.com --alias main
+  camo start worker-1 --headless --alias shard1 --idle-timeout 45m
+  camo start myprofile --width 1920 --height 1020
+  camo stop --id inst_xxxxxxxx
+  camo stop --alias shard1
+  camo stop idle
+  camo close all
   camo goto https://www.xiaohongshu.com
   camo scroll --down --amount 500
   camo click "#search-input"
@@ -108,6 +119,7 @@ EXAMPLES:
   camo mouse wheel --deltay -300
   camo system display
   camo sessions
+  camo instances
   camo cleanup myprofile
   camo force-stop myprofile
   camo lock list