@petercjl/ecom-cli 0.3.0 → 0.3.2

package/README.md

@@ -30,7 +30,7 @@ Task entry checks stable `latest` at most daily, with a 1.5 second bound. Detect
 
 ## Developer contract
 
-`ecom-cli help --json`, `version --json`, `capabilities --json`, `schema --json`, and `doctor --json` expose supported commands and versioned results. Errors use JSON with stable codes; exit code 2 means invalid arguments, 1 means operational failure. stdout contains results; stderr contains diagnostics. Multiple Ecom instances require explicit `--profile` or `--instance` selection. Connection authenticates through owner-only local mailbox files, verifies the live Ecom executable, and uses no remote debugging port.
+`ecom-cli help --json`, `version --json`, `capabilities --json`, `schema --json`, and `doctor --json` expose supported commands and versioned results. Errors use JSON with stable codes; exit code 2 means invalid arguments, 1 means operational failure. stdout contains results; stderr contains diagnostics. The CLI selects stable Ecom by default. Select Dev explicitly with `--profile` or `--instance`. If more than one instance matches, pin the desired profile or instance. Connection authenticates through owner-only local mailbox files, verifies the live Ecom executable, and uses no remote debugging port.
 
 The browser owns sessions, containers and authorization. This package owns discovery, read-only transport and managed installation. The Skill documents invocation, diagnosis and recovery. Additional browser capabilities will extend this same command/Skill contract.
 
@@ -49,3 +49,26 @@ The browser owns sessions, containers and authorization. This package owns disco
 开发者通过 `sycm operations`、`sycm schema --operation ID`、`sycm run --operation ID --container VALUE --params-json JSON` 发现和调用原子取数能力；`sycm mutation plan/show/apply` 承接计划与确认。所有命令均支持结构化 JSON。
 
 取数优先使用后台原生请求。需要准备平台会话时，当前 Agent 可通过 `sycm open --operation ID --container VALUE` 在该容器打开注册入口，默认后台打开或复用；`--foreground` 用于明确需要前台的登录与验证。登录完成后继续调用原生接口，保留账号已设置的首页。
+# Memory diagnostics (P0)
+
+`ecom-cli memory status|tabs|processes|containers --json` returns one complete native snapshot, including effective policy, process memory, estimated tab/container shares and separate freeze/discard reasons. Select an exact `--instance` or `--profile` when more than one browser is running. Requires a browser advertising `memorySnapshotProtocol: 1`; macOS is the currently verified transport. No tabs are navigated, frozen or discarded. Shared processes are counted once; estimates are not reclaimable bytes. Unknown metrics are null and incomplete totals are identified. Origins exclude URL paths and queries; labels and titles remain user data. All four views preserve the full snapshot for consistent relationships. Windows GUI sampling is implemented separately and awaits native validation.
+
+## Manual tab sleep MVP
+
+`tabs discard|wake --tab ID --container ID --expected-page-version VERSION --instance INSTANCE --json` explicitly releases or reloads one selected page in its original container. Obtain exact identities from a fresh memory snapshot; use `@default` for the default session. The native layer rechecks protections and a 30-second recent-use window; there is no force override. Wake runs in the background and reports navigation start, not login/load completion. Query `memory operation --operation-id UUID --instance INSTANCE --json` after uncertain outcomes; missing records mean unknown execution. Records cover the latest 128 actions per profile until restart. Requires `manualTabMemoryProtocol=1`. Persistent account storage is retained; external page tasks use the keep-running contract below.
+
+### Automatic idle sleep
+
+`memory auto status` reports persistent settings and run-local scan/discard counters. With explicit configuration intent, `memory auto set --enabled on --idle-seconds 1200 --instance ID --json` enables a 20-minute threshold; `--enabled off` stops future scans. Supported idle thresholds are 60–86400 seconds, scans run every 30 seconds and discard at most one eligible background tab. Original container storage stays intact and wake reloads the page.
+
+Snapshots expose each tab's `automatic` idle time, protection reasons and `keepAwake`. Use `tabs protect --tab ID --container ID --expected-page-version VERSION --keep-awake on|off --instance ID --json` around page-backed tasks outside native integration. Protection lasts until release, tab close or browser restart and does not wake sleeping tabs. Task cleanup releases it using a fresh target version. Edited forms, native user edits, media (including muted video), uploads and integrated native tasks have shared automatic/manual guards. Unknown business state requires explicit keep-running protection. Settings/exception requests have idempotent desired state; after an unknown outcome read settings/snapshot before retrying. Windows native transport remains unverified.
+
+Native playback observation preserves background playback intent when Chromium suspends muted media on hiding it. Revisit and pause to release that conservative protection; navigation clears the old page state. Selecting a sleeping tab reloads it through the native tab model.
+
+`manualDiscard.editSignals` reports native form interaction and user-edit flags, plus whether a leave confirmation is possible. Listener presence alone is informational and does not block sleep; native PROACTIVE editing protections and task guards still apply. Unavailable edit flags remain null. These are conservative native edit-history signals, not a universal saved/unsaved business-state detector; use explicit keep-running protection for custom editor/task state outside native detection. The browser never dispatches unload handlers speculatively to classify a page.
+
+### On-demand session restoration (P2)
+
+`memory restore status --instance ID --json` exposes native startup settings and the background restoration queue. `memory restore set --lazy-startup on --max-background 2 --instance ID --json` persists selected-tab-only startup (default) and a 1–4 background admission limit (default 2). Disabling lazy startup queues all restored background tabs. Startup mode applies next restore; concurrency changes govern new admissions and let existing loads finish. GUI provides the same settings and deferred/queued/loading states.
+
+Exact-target `tabs wake` may return `navigation-queued` plus a request ID; poll snapshots or `memory operation` for current restore state. Selecting a tab loads it immediately ahead of waiting background work. The queue holds slots until load stop/closure and rechecks target identity on admission. Native network reads need no webpage; protected fresh page-backed tasks keep their existing separate concurrency. Queue settings do not limit arbitrary user navigation. Platform login/loading success require separate readback. Explicit queue capacity is 32; active/queued work and bounded history are visible. Unknown outcomes require inspection before retry. Windows native runtime remains separately unverified.