niahere 0.2.85 → 0.2.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.2.85",
+  "version": "0.2.86",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {

package/skills/qa/SKILL.md

@@ -25,7 +25,7 @@ allowed-tools:
 
 You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence.
 
-For Playwright MCP reference, see [playwright.md](playwright.md)
+For Playwright MCP reference and the cloned-profile helper workflow, see [playwright.md](playwright.md).
 
 ## Setup
 

package/skills/qa/playwright.md

@@ -6,7 +6,7 @@
 
 ## How Playwright Works Here
 
-Playwright is available as **MCP tools already in your tool list**. You do NOT need to:
+Playwright is usually available as **MCP tools already in your tool list**. You do NOT need to:
 - Install anything (`npm install playwright`, `npx playwright install` — NO)
 - Import or require playwright in code
 - Write scripts or launch a browser manually
@@ -14,7 +14,85 @@ Playwright is available as **MCP tools already in your tool list**. You do NOT n
 
 **Just call the tools directly.** They are prefixed `mcp__plugin_playwright_playwright__` in your tool list (e.g., `mcp__plugin_playwright_playwright__browser_navigate`). Search your available tools for `browser_` to see them all.
 
-A persistent Chrome profile at `~/.shared/playwright-profile/` is pre-configured with saved logins. The browser launches automatically on your first tool call and reuses this profile.
+A persistent Chrome profile is available for saved logins. For ordinary browser work, use the MCP tools directly. For parallel agents or sites that block fresh Chromium, use the cloned-profile helper below.
+
+## Cloned Profile Helper
+
+Use this when multiple agents need browser access from a warmed profile, or when a site blocks clean Playwright Chromium.
+
+Helper:
+
+```bash
+skills/qa/scripts/playwright-profile-clone.sh
+```
+
+Default canonical profile:
+
+```text
+~/.shared/playwright-user-profile
+```
+
+If that profile does not exist, the helper creates it. If `~/.shared/playwright-config.json` has a `browser.userDataDir`, the helper seeds `playwright-user-profile` from that existing configured profile on first use.
+
+### Open a cloned browser
+
+```bash
+skills/qa/scripts/playwright-profile-clone.sh open
+```
+
+This:
+- generates a random hex run id
+- copies the canonical profile to `~/.shared/playwright-profile-runs/<run-id>`
+- launches Chrome with that copied `--user-data-dir`
+- assigns a free `--remote-debugging-port`
+- prints `PW_PROFILE_RUN_ID`, `PW_USER_DATA_DIR`, `PW_CDP_URL`, and `PW_PROFILE_CLOSE_ACTION`
+- watches the Chrome process; when Chrome exits, commits the run profile back to the canonical profile and removes the run clone
+
+Each concurrent `open` gets its own user-data dir and CDP URL.
+
+Attach with Playwright when needed:
+
+```js
+const { chromium } = require("playwright");
+const browser = await chromium.connectOverCDP(process.env.PW_CDP_URL);
+const context = browser.contexts()[0];
+const page = context.pages()[0] || await context.newPage();
+```
+
+### Close behavior
+
+Default close behavior is `commit`: when the Chrome process exits, the helper backs up the canonical profile, overwrites it from the run profile, and deletes the run clone.
+
+Use `--discard-on-close` for throwaway browser work:
+
+```bash
+skills/qa/scripts/playwright-profile-clone.sh open --discard-on-close
+```
+
+Use `--keep` when debugging or when you want to commit and cleanup manually:
+
+```bash
+skills/qa/scripts/playwright-profile-clone.sh open --keep
+skills/qa/scripts/playwright-profile-clone.sh commit --run-id <run-id>
+skills/qa/scripts/playwright-profile-clone.sh cleanup --run-id <run-id>
+```
+
+`commit` backs up the canonical profile and overwrites it from the run profile. `cleanup` removes the run profile. If multiple runs are active, pass `--run-id`; do not rely on a global current pointer.
+
+Atomic commands:
+
+```bash
+skills/qa/scripts/playwright-profile-clone.sh prepare
+skills/qa/scripts/playwright-profile-clone.sh open
+skills/qa/scripts/playwright-profile-clone.sh open --discard-on-close
+skills/qa/scripts/playwright-profile-clone.sh open --keep
+skills/qa/scripts/playwright-profile-clone.sh status --run-id <run-id>
+skills/qa/scripts/playwright-profile-clone.sh commit --run-id <run-id>
+skills/qa/scripts/playwright-profile-clone.sh cleanup --run-id <run-id>
+skills/qa/scripts/playwright-profile-clone.sh prune --keep 100
+```
+
+The helper auto-prunes old run profiles after `prepare`/`open`. Default cap is `100` run dirs. Override it with `PLAYWRIGHT_PROFILE_MAX_RUNS=<count>`, or disable automatic pruning with `PLAYWRIGHT_PROFILE_MAX_RUNS=0` or `PLAYWRIGHT_PROFILE_MAX_RUNS=off`. Pruning skips the current run and any run with a tracked live Chrome PID.
 
 ## Quickstart: Open a Browser
 
@@ -183,23 +261,24 @@ When the snapshot is too large, it auto-saves to a file. Use Grep on the saved f
 ## Session Management & Persistent Chrome Profile
 
 ### Profile Location
-- **Persistent profile**: `~/.shared/playwright-profile/` — cookies, logins, and browser state persist across sessions and agents
+- **Canonical cloned profile**: `~/.shared/playwright-user-profile/` — cookies, logins, and browser state used as the source for copied runs
+- **Run profiles**: `~/.shared/playwright-profile-runs/<run-id>/` — per-agent copied profiles
 - **Config**: `~/.shared/playwright-config.json` — controls browser type, headless mode, and profile path
 - **MCP registration**: `~/.claude/plugins/.../playwright/.mcp.json` — must include `--config` flag pointing to the config file
 
 ### How It Works
 - Playwright launches a **separate Chrome instance** using the persistent profile — won't conflict with your running Chrome
 - Log in manually once in the Playwright Chrome window (e.g., App Store Connect, RevenueCat), sessions persist across restarts and new conversations
-- Any agent or session that uses Playwright MCP shares the same profile — no re-login needed
+- For parallel spawned agents, use copied run profiles. Do not launch multiple Chrome instances against the same user-data dir.
 
 ### If Sessions Expire or Browser Won't Connect
-- **"Opening in existing browser session" error**: A Chrome instance with this profile is already running. Find and kill it:
+- **"Opening in existing browser session" error**: A Chrome instance with this profile is already running. For cloned runs, open a new clone instead of reusing the same run id. If you intentionally need to stop an old canonical-profile browser:
   ```bash
-  ps aux | grep "user-data-dir=/Users/aman/.shared/playwright-profile" | grep -v grep | grep -v "Helper" | awk '{print $2}' | xargs kill
+  ps aux | grep "user-data-dir=.*playwright-user-profile" | grep -v grep | grep -v "Helper" | awk '{print $2}' | xargs kill
   ```
   Then retry the Playwright action. The persistent profile (cookies/logins) is on disk and survives browser restarts.
 - **Auth expired?** Navigate to the login page in the Playwright Chrome window and re-login — the new session will persist automatically.
-- **Random cache profiles**: If Chrome uses `/Library/Caches/ms-playwright/mcp-chrome-*` instead of the persistent profile, the `--config` flag is missing from the MCP registration. Fix: ensure `~/.claude/plugins/.../playwright/.mcp.json` includes `"--config", "/Users/aman/.claude/playwright-config.json"` in the args array.
+- **Random cache profiles**: If Chrome uses `/Library/Caches/ms-playwright/mcp-chrome-*` instead of the persistent profile, the `--config` flag is missing from the MCP registration. Fix: ensure the Playwright MCP registration includes `"--config", "~/.shared/playwright-config.json"` in the args array.
 
 ### Logged-In Services (as of Feb 2026)
 - Apple App Store Connect (`appstoreconnect.apple.com`)
@@ -230,7 +309,7 @@ When the snapshot is too large, it auto-saves to a file. Use Grep on the saved f
 | Navigate without waiting | Always `wait_for` before reading content |
 | Keep browser open indefinitely | Close when done to free resources |
 | Ignore snapshot file saves | Grep/parse the saved file for large outputs |
-| Try to launch/setup browser manually | Just call `browser_navigate` — it auto-launches |
+| Launch Chrome manually for ordinary QA | Use `browser_navigate`; use `playwright-profile-clone.sh open` only when a copied warmed profile is needed |
 
 ## Debugging Tips
 

package/skills/qa/scripts/playwright-profile-clone.sh

@@ -0,0 +1,535 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROFILE_HOME="${PLAYWRIGHT_PROFILE_HOME:-$HOME/.shared}"
+CONFIG_PATH="${PLAYWRIGHT_CONFIG:-$PROFILE_HOME/playwright-config.json}"
+RUNS_DIR="${PLAYWRIGHT_PROFILE_RUNS_DIR:-$PROFILE_HOME/playwright-profile-runs}"
+BACKUPS_DIR="${PLAYWRIGHT_PROFILE_BACKUPS_DIR:-$PROFILE_HOME/playwright-profile-backups}"
+STATE_DIR="$RUNS_DIR/.state"
+MAX_RUNS="${PLAYWRIGHT_PROFILE_MAX_RUNS:-100}"
+SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+COMMIT_LOCK_HELD=""
+
+usage() {
+  cat <<'EOF'
+Usage:
+  playwright-profile-clone.sh prepare [--run-id <hex>] [--primary <path>]
+  playwright-profile-clone.sh open [--run-id <hex>] [--primary <path>] [--commit-on-close|--discard-on-close|--keep]
+  playwright-profile-clone.sh commit [--run-id <hex>]
+  playwright-profile-clone.sh cleanup [--run-id <hex>]
+  playwright-profile-clone.sh prune [--keep <count>|--off]
+  playwright-profile-clone.sh status [--run-id <hex>]
+
+Environment:
+  PW_PRIMARY_PROFILE            Canonical source profile override
+  PLAYWRIGHT_USER_PROFILE       Canonical source profile override
+  PLAYWRIGHT_PROFILE_HOME       Base dir, default: ~/.shared
+  PLAYWRIGHT_CONFIG             Config to seed from, default: ~/.shared/playwright-config.json
+  PLAYWRIGHT_CHROME             Chrome executable override
+  PLAYWRIGHT_PROFILE_MAX_RUNS   Max run dirs to keep, default: 100; set 0/off to disable auto-prune
+EOF
+}
+
+die() {
+  echo "error=$*" >&2
+  exit 1
+}
+
+release_commit_lock() {
+  if [ -n "$COMMIT_LOCK_HELD" ]; then
+    rmdir "$COMMIT_LOCK_HELD" 2>/dev/null || true
+    COMMIT_LOCK_HELD=""
+  fi
+}
+
+trap release_commit_lock EXIT
+
+shell_quote() {
+  printf "%q" "$1"
+}
+
+random_hex() {
+  if command -v openssl >/dev/null 2>&1; then
+    openssl rand -hex 4
+  else
+    node -e "console.log(require('crypto').randomBytes(4).toString('hex'))"
+  fi
+}
+
+configured_profile() {
+  [ -f "$CONFIG_PATH" ] || return 0
+  command -v node >/dev/null 2>&1 || return 0
+  node - "$CONFIG_PATH" <<'NODE'
+const fs = require("fs");
+const config = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const dir = config?.browser?.userDataDir || config?.browser?.launchOptions?.userDataDir || "";
+if (dir) process.stdout.write(dir);
+NODE
+}
+
+resolve_primary() {
+  local explicit="$1"
+  if [ -n "$explicit" ]; then
+    echo "$explicit"
+  elif [ -n "${PW_PRIMARY_PROFILE:-}" ]; then
+    echo "$PW_PRIMARY_PROFILE"
+  elif [ -n "${PLAYWRIGHT_USER_PROFILE:-}" ]; then
+    echo "$PLAYWRIGHT_USER_PROFILE"
+  else
+    echo "$PROFILE_HOME/playwright-user-profile"
+  fi
+}
+
+has_entries() {
+  [ -d "$1" ] && [ -n "$(find "$1" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null)" ]
+}
+
+copy_profile() {
+  local source="$1"
+  local destination="$2"
+  mkdir -p "$destination"
+  rsync -a --delete \
+    --exclude='Singleton*' \
+    --exclude='DevToolsActivePort' \
+    --exclude='BrowserMetrics/' \
+    --exclude='Crashpad/' \
+    --exclude='Default/Cache/' \
+    --exclude='Default/Code Cache/' \
+    --exclude='Default/GPUCache/' \
+    --exclude='Default/DawnGraphiteCache/' \
+    --exclude='Default/DawnWebGPUCache/' \
+    --exclude='GrShaderCache/' \
+    --exclude='GraphiteDawnCache/' \
+    --exclude='ShaderCache/' \
+    "$source/" "$destination/"
+}
+
+acquire_commit_lock() {
+  mkdir -p "$BACKUPS_DIR"
+  local lock_dir="$BACKUPS_DIR/.commit.lock"
+  local deadline=$((SECONDS + 60))
+
+  while ! mkdir "$lock_dir" 2>/dev/null; do
+    if [ "$SECONDS" -ge "$deadline" ]; then
+      die "timed out waiting for profile commit lock"
+    fi
+    sleep 0.2
+  done
+
+  COMMIT_LOCK_HELD="$lock_dir"
+}
+
+prune_old_runs() {
+  local protected_run_id="${1:-}"
+  local max_runs="${2:-$MAX_RUNS}"
+  local quiet="${3:-quiet}"
+
+  RUNS_DIR="$RUNS_DIR" STATE_DIR="$STATE_DIR" PROTECTED_RUN_ID="$protected_run_id" MAX_RUNS="$max_runs" QUIET="$quiet" node <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const runsDir = process.env.RUNS_DIR;
+const stateDir = process.env.STATE_DIR;
+const protectedRunId = process.env.PROTECTED_RUN_ID || "";
+const rawMax = String(process.env.MAX_RUNS || "100").toLowerCase();
+const quiet = process.env.QUIET === "quiet";
+
+if (["0", "off", "false", "none", "disabled"].includes(rawMax)) {
+  if (!quiet) console.log("profile_prune=disabled");
+  process.exit(0);
+}
+
+const max = Number.parseInt(rawMax, 10);
+if (!Number.isFinite(max) || max < 1) {
+  console.error(`error=invalid PLAYWRIGHT_PROFILE_MAX_RUNS: ${process.env.MAX_RUNS}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(runsDir)) {
+  if (!quiet) console.log("profile_pruned=0");
+  process.exit(0);
+}
+
+function parseState(runId) {
+  const file = path.join(stateDir, `${runId}.env`);
+  if (!fs.existsSync(file)) return {};
+  const state = {};
+  for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (!match) continue;
+    state[match[1]] = match[2].replace(/^'(.*)'$/, "$1").replace(/^"(.*)"$/, "$1");
+  }
+  return state;
+}
+
+function pidIsAlive(pid) {
+  const numericPid = Number.parseInt(pid || "", 10);
+  if (!numericPid) return false;
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const runs = fs.readdirSync(runsDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name !== ".state")
+  .map((entry) => {
+    const runDir = path.join(runsDir, entry.name);
+    return {
+      id: entry.name,
+      dir: runDir,
+      mtimeMs: fs.statSync(runDir).mtimeMs,
+      state: parseState(entry.name),
+    };
+  })
+  .sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+let remaining = runs.length;
+let pruned = 0;
+
+for (const run of runs) {
+  if (remaining <= max) break;
+  if (run.id === protectedRunId) continue;
+  if (pidIsAlive(run.state.PW_CHROME_PID)) continue;
+
+  fs.rmSync(run.dir, { recursive: true, force: true });
+  fs.rmSync(path.join(stateDir, `${run.id}.env`), { force: true });
+  fs.rmSync(path.join(runsDir, `${run.id}.chrome.log`), { force: true });
+  remaining -= 1;
+  pruned += 1;
+}
+
+if (!quiet) {
+  console.log(`profile_pruned=${pruned}`);
+  console.log(`profile_runs=${remaining}`);
+  console.log(`profile_max_runs=${max}`);
+}
+NODE
+}
+
+seed_primary_if_needed() {
+  local primary="$1"
+  mkdir -p "$(dirname "$primary")"
+
+  if has_entries "$primary"; then
+    return 0
+  fi
+
+  local configured
+  configured="$(configured_profile || true)"
+  if [ -n "$configured" ] && [ "$configured" != "$primary" ] && has_entries "$configured"; then
+    copy_profile "$configured" "$primary"
+  else
+    mkdir -p "$primary"
+  fi
+}
+
+state_file() {
+  echo "$STATE_DIR/$1.env"
+}
+
+write_state() {
+  local run_id="$1"
+  local status="$2"
+  local primary="$3"
+  local run_dir="$4"
+  local cdp_url="${5:-}"
+  local chrome_pid="${6:-}"
+  local close_action="${7:-manual}"
+
+  mkdir -p "$STATE_DIR"
+  {
+    echo "PW_PROFILE_RUN_ID=$(shell_quote "$run_id")"
+    echo "PW_PRIMARY_PROFILE=$(shell_quote "$primary")"
+    echo "PW_USER_DATA_DIR=$(shell_quote "$run_dir")"
+    echo "PW_CDP_URL=$(shell_quote "$cdp_url")"
+    echo "PW_CHROME_PID=$(shell_quote "$chrome_pid")"
+    echo "PW_PROFILE_STATUS=$(shell_quote "$status")"
+    echo "PW_PROFILE_CLOSE_ACTION=$(shell_quote "$close_action")"
+  } >"$(state_file "$run_id")"
+}
+
+load_state() {
+  local run_id="$1"
+  local file
+  file="$(state_file "$run_id")"
+  [ -f "$file" ] || die "unknown run id: $run_id"
+  # shellcheck disable=SC1090
+  source "$file"
+}
+
+single_active_run_id() {
+  mkdir -p "$STATE_DIR"
+  local ids=()
+  local file
+  while IFS= read -r file; do
+    ids+=("$(basename "$file" .env)")
+  done < <(find "$STATE_DIR" -maxdepth 1 -type f -name '*.env' -print | sort)
+
+  if [ "${#ids[@]}" -eq 1 ]; then
+    echo "${ids[0]}"
+  elif [ "${#ids[@]}" -eq 0 ]; then
+    die "no active profile runs; pass --run-id"
+  else
+    printf 'active_runs=' >&2
+    printf '%s ' "${ids[@]}" >&2
+    printf '\n' >&2
+    die "multiple active profile runs; pass --run-id"
+  fi
+}
+
+resolve_run_id_arg() {
+  local explicit="$1"
+  if [ -n "$explicit" ]; then
+    echo "$explicit"
+  elif [ -n "${PW_PROFILE_RUN_ID:-}" ]; then
+    echo "$PW_PROFILE_RUN_ID"
+  else
+    single_active_run_id
+  fi
+}
+
+print_exports() {
+  local run_id="$1"
+  local primary="$2"
+  local run_dir="$3"
+  local cdp_url="${4:-}"
+  echo "PW_PROFILE_RUN_ID='${run_id}'"
+  echo "PW_PRIMARY_PROFILE='${primary}'"
+  echo "PW_USER_DATA_DIR='${run_dir}'"
+  if [ -n "$cdp_url" ]; then
+    echo "PW_CDP_URL='${cdp_url}'"
+  fi
+  echo "export PW_PROFILE_RUN_ID PW_PRIMARY_PROFILE PW_USER_DATA_DIR${cdp_url:+ PW_CDP_URL}"
+}
+
+prepare_profile() {
+  local run_id="$1"
+  local primary="$2"
+  local run_dir="$RUNS_DIR/$run_id"
+
+  seed_primary_if_needed "$primary"
+  copy_profile "$primary" "$run_dir"
+  write_state "$run_id" "prepared" "$primary" "$run_dir"
+  prune_old_runs "$run_id"
+  print_exports "$run_id" "$primary" "$run_dir"
+}
+
+free_port() {
+  node <<'NODE'
+const net = require("net");
+const server = net.createServer();
+server.listen(0, "127.0.0.1", () => {
+  const port = server.address().port;
+  server.close(() => console.log(port));
+});
+NODE
+}
+
+chrome_path() {
+  if [ -n "${PLAYWRIGHT_CHROME:-}" ]; then
+    echo "$PLAYWRIGHT_CHROME"
+  elif [ -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ]; then
+    echo "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  elif command -v google-chrome >/dev/null 2>&1; then
+    command -v google-chrome
+  elif command -v chromium >/dev/null 2>&1; then
+    command -v chromium
+  elif command -v chromium-browser >/dev/null 2>&1; then
+    command -v chromium-browser
+  else
+    die "could not find Chrome/Chromium; set PLAYWRIGHT_CHROME"
+  fi
+}
+
+cmd_prepare() {
+  local run_id=""
+  local primary_arg=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --run-id) run_id="${2:-}"; shift 2 ;;
+      --primary) primary_arg="${2:-}"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown prepare arg: $1" ;;
+    esac
+  done
+  [ -n "$run_id" ] || run_id="$(random_hex)"
+  prepare_profile "$run_id" "$(resolve_primary "$primary_arg")"
+}
+
+cmd_open() {
+  local run_id=""
+  local primary_arg=""
+  local close_action="commit"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --run-id) run_id="${2:-}"; shift 2 ;;
+      --primary) primary_arg="${2:-}"; shift 2 ;;
+      --commit-on-close) close_action="commit"; shift ;;
+      --discard-on-close) close_action="discard"; shift ;;
+      --keep) close_action="keep"; shift ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown open arg: $1" ;;
+    esac
+  done
+  [ -n "$run_id" ] || run_id="$(random_hex)"
+  local primary run_dir port cdp_url chrome log_file
+  primary="$(resolve_primary "$primary_arg")"
+  run_dir="$RUNS_DIR/$run_id"
+  prepare_profile "$run_id" "$primary" >/dev/null
+  port="$(free_port)"
+  cdp_url="http://127.0.0.1:$port"
+  chrome="$(chrome_path)"
+  log_file="$RUNS_DIR/$run_id.chrome.log"
+
+  "$chrome" \
+    --user-data-dir="$run_dir" \
+    --remote-debugging-port="$port" \
+    --no-first-run \
+    --no-default-browser-check \
+    about:blank >"$log_file" 2>&1 &
+  local chrome_pid=$!
+  write_state "$run_id" "opened" "$primary" "$run_dir" "$cdp_url" "$chrome_pid" "$close_action"
+  start_close_watchdog "$run_id" "$chrome_pid" "$close_action" "$log_file"
+  print_exports "$run_id" "$primary" "$run_dir" "$cdp_url"
+  echo "PW_CHROME_PID='${chrome_pid}'"
+  echo "PW_CHROME_LOG='${log_file}'"
+  echo "PW_PROFILE_CLOSE_ACTION='${close_action}'"
+}
+
+commit_profile() {
+  local run_id="$1"
+  local allow_running="${2:-false}"
+  load_state "$run_id"
+
+  if [ "$allow_running" != "true" ] && [ -n "${PW_CHROME_PID:-}" ] && kill -0 "$PW_CHROME_PID" 2>/dev/null; then
+    die "browser still running for run id $run_id; close it before commit"
+  fi
+
+  acquire_commit_lock
+  local backup="$BACKUPS_DIR/$run_id-$(date +%Y%m%d%H%M%S)"
+  if has_entries "$PW_PRIMARY_PROFILE"; then
+    copy_profile "$PW_PRIMARY_PROFILE" "$backup"
+  else
+    mkdir -p "$backup"
+  fi
+  copy_profile "$PW_USER_DATA_DIR" "$PW_PRIMARY_PROFILE"
+  write_state "$run_id" "committed" "$PW_PRIMARY_PROFILE" "$PW_USER_DATA_DIR" "${PW_CDP_URL:-}" "${PW_CHROME_PID:-}" "${PW_PROFILE_CLOSE_ACTION:-manual}"
+  echo "status=committed"
+  echo "run_id=$run_id"
+  echo "backup=$backup"
+  release_commit_lock
+}
+
+cleanup_profile() {
+  local run_id="$1"
+  load_state "$run_id"
+  rm -rf "$PW_USER_DATA_DIR" "$(state_file "$run_id")" "$RUNS_DIR/$run_id.chrome.log"
+  echo "status=cleaned"
+  echo "run_id=$run_id"
+}
+
+start_close_watchdog() {
+  local run_id="$1"
+  local chrome_pid="$2"
+  local close_action="$3"
+  local log_file="$4"
+
+  [ "$close_action" != "keep" ] || return 0
+
+  (
+    while kill -0 "$chrome_pid" 2>/dev/null; do
+      sleep 0.2
+    done
+
+    if [ "$close_action" = "commit" ]; then
+      bash "$SCRIPT_PATH" commit --run-id "$run_id" --assume-closed >>"$log_file" 2>&1 &&
+        bash "$SCRIPT_PATH" cleanup --run-id "$run_id" >>"$log_file" 2>&1
+    elif [ "$close_action" = "discard" ]; then
+      bash "$SCRIPT_PATH" cleanup --run-id "$run_id" >>"$log_file" 2>&1
+    fi
+  ) >/dev/null 2>&1 &
+}
+
+cmd_commit() {
+  local run_id_arg=""
+  local allow_running="false"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --run-id) run_id_arg="${2:-}"; shift 2 ;;
+      --assume-closed) allow_running="true"; shift ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown commit arg: $1" ;;
+    esac
+  done
+
+  local run_id
+  run_id="$(resolve_run_id_arg "$run_id_arg")"
+  commit_profile "$run_id" "$allow_running"
+}
+
+cmd_cleanup() {
+  local run_id_arg=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --run-id) run_id_arg="${2:-}"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown cleanup arg: $1" ;;
+    esac
+  done
+
+  local run_id
+  run_id="$(resolve_run_id_arg "$run_id_arg")"
+  cleanup_profile "$run_id"
+}
+
+cmd_prune() {
+  local keep="$MAX_RUNS"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --keep) keep="${2:-}"; shift 2 ;;
+      --off) keep="off"; shift ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown prune arg: $1" ;;
+    esac
+  done
+
+  prune_old_runs "" "$keep" "verbose"
+}
+
+cmd_status() {
+  local run_id_arg=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --run-id) run_id_arg="${2:-}"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown status arg: $1" ;;
+    esac
+  done
+
+  local run_id
+  run_id="$(resolve_run_id_arg "$run_id_arg")"
+  cat "$(state_file "$run_id")"
+}
+
+main() {
+  local command="${1:-}"
+  [ -n "$command" ] || { usage; exit 1; }
+  shift || true
+  mkdir -p "$RUNS_DIR" "$STATE_DIR"
+
+  case "$command" in
+    prepare) cmd_prepare "$@" ;;
+    open) cmd_open "$@" ;;
+    commit) cmd_commit "$@" ;;
+    cleanup) cmd_cleanup "$@" ;;
+    prune) cmd_prune "$@" ;;
+    status) cmd_status "$@" ;;
+    -h|--help) usage ;;
+    *) die "unknown command: $command" ;;
+  esac
+}
+
+main "$@"

package/skills/whisper-cpp-transcribe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whisper-cpp-transcribe
-description: Transcribe or subtitle audio/video files using whisper.cpp (whisper-cpp), with a default large-v3 model path and ffmpeg-based extraction.
+description: Transcribe or subtitle audio/video files using whisper.cpp (whisper-cpp), with a default medium model path and ffmpeg-based extraction.
 ---
 
 ## Overview
@@ -8,29 +8,50 @@ Use this skill when the user wants Whisper.cpp to convert speech in local media
 
 ## Quick Start
 1. Confirm `whisper-cpp` is installed and discoverable (`whisper-cli -h`).
+   - If missing on macOS with Homebrew available, install it with `brew install whisper-cpp`.
+   - Do not reinstall when present. Use `brew upgrade whisper-cpp` only when the user explicitly asks to update the installed package.
 2. Resolve input type:
    - If input is video or unsupported audio format, extract WAV first with `ffmpeg`.
    - If input is WAV/MP3/OGG/FLAC, pass it directly.
-3. Ensure model path exists: `$HOME/.cache/whisper-cpp/models/ggml-large-v3.bin`.
+3. Ensure model path exists: `$HOME/.cache/whisper-cpp/models/ggml-medium.bin`.
 4. Run `whisper-cli` with `-m <model>` and `-f <input>` and requested output flags (`-otxt`, `-osrt`, etc.).
 5. Clean up temporary extracted files.
 
+## Install / Update
+- Check first:
+  - `command -v whisper-cli`
+  - `whisper-cli -h`
+- If `whisper-cli` is missing and Homebrew is available:
+  - `brew install whisper-cpp`
+- If `whisper-cli` is present:
+  - do not install again
+- If the user explicitly asks to update the installed package:
+  - `brew upgrade whisper-cpp`
+
 ## Default Model
-- Primary model: `ggml-large-v3.bin`
+- Primary model: `ggml-medium.bin`
 - Default location expected by this skill:
-  - `"$HOME/.cache/whisper-cpp/models/ggml-large-v3.bin"`
-- If the file is missing:
-  - Download on stable Wi-Fi only:
-    - `curl -L --fail --show-error -o "$HOME/.cache/whisper-cpp/models/ggml-large-v3.bin" https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin`
+  - `"$HOME/.cache/whisper-cpp/models/ggml-medium.bin"`
+- Expected file:
+  - size: `1533763059` bytes
+  - SHA-256: `6c14d5adee5f86394037b4e4e8b59f1673b6cee10e3cf0b11bbdbee79c156208`
+- If the file is missing or does not match the expected size/hash:
+  - Download on stable Wi-Fi only, using a resumable temporary file and atomic rename:
+    - `mkdir -p "$HOME/.cache/whisper-cpp/models"`
+    - `curl -L -C - --fail --show-error --retry 5 --retry-delay 2 -o "$HOME/.cache/whisper-cpp/models/ggml-medium.bin.tmp" https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin`
+    - `test "$(wc -c < "$HOME/.cache/whisper-cpp/models/ggml-medium.bin.tmp" | tr -d ' ')" = "1533763059"`
+    - `test "$(shasum -a 256 "$HOME/.cache/whisper-cpp/models/ggml-medium.bin.tmp" | cut -d' ' -f1)" = "6c14d5adee5f86394037b4e4e8b59f1673b6cee10e3cf0b11bbdbee79c156208"`
+    - `mv "$HOME/.cache/whisper-cpp/models/ggml-medium.bin.tmp" "$HOME/.cache/whisper-cpp/models/ggml-medium.bin"`
 
 ## Workflow
 - Install check:
+  - `command -v whisper-cli || brew install whisper-cpp`
   - `whisper-cli -h`
   - `ffmpeg -version` (required only when input video or unsupported audio format is used)
 - Extract audio when needed:
   - `ffmpeg -y -i "<input>" -ac 1 -ar 16000 -c:a pcm_s16le "<tmp>.wav"`
 - Transcribe:
-  - `whisper-cli -m "$HOME/.cache/whisper-cpp/models/ggml-large-v3.bin" -f "<audio>" -otxt -osrt`
+  - `whisper-cli -m "$HOME/.cache/whisper-cpp/models/ggml-medium.bin" -f "<audio>" -otxt -osrt`
 - Optional translation:
   - append `-tr`
 - Optional language override:
@@ -39,9 +60,9 @@ Use this skill when the user wants Whisper.cpp to convert speech in local media
   - `-of "<output-path-without-extension>"`
 
 ## Decision Points
-- If download bandwidth is constrained, ask before downloading the large-v3 model.
+- If download bandwidth is constrained, ask before downloading the medium model.
 - If input is a large file and hardware is limited:
-  - suggest `small`/`base` model first, then run `large-v3` if needed.
+  - suggest `small`/`base` model first, then run `medium` if needed.
 - If only subtitle output is requested:
   - use `-osrt` or `-ovtt` instead of `-otxt`.
 - If audio is noisy and transcripts are poor:
@@ -49,6 +70,9 @@ Use this skill when the user wants Whisper.cpp to convert speech in local media
     - `--vad -vm ggml-silero-v6.2.0.bin` after obtaining the VAD model.
 
 ## Validation
+- Confirm model integrity:
+  - `wc -c "$HOME/.cache/whisper-cpp/models/ggml-medium.bin"`
+  - `shasum -a 256 "$HOME/.cache/whisper-cpp/models/ggml-medium.bin"`
 - Run one small sample and inspect:
   - generated `<input>.txt`
   - generated `<input>.srt` (if requested)