ask-pro 0.1.69 → 0.1.71

package/README.md

@@ -6,39 +6,47 @@ and owns the result; ask-pro never applies generated code.
 
 ## Install
 
-```powershell
-npx skills add JJLiebig/ask-pro -g
-```
-
-This installs the `ask-pro` skill for Codex, Claude Code, and the other agents
-the [skills CLI](https://github.com/vercel-labs/skills) supports. The skill
-contains ask-pro itself; its first run installs dependencies and builds, so no
-separate CLI install is needed. Update with `npx skills update`.
+Both options need Node.js 24+, Chrome, and a ChatGPT account with Pro access.
+Browser login is manual.
 
-Codex users can install it as a plugin instead:
+### Codex plugin marketplace
 
 ```powershell
 codex plugin marketplace add JJLiebig/ask-pro
 codex plugin add ask-pro@ask-pro
 ```
 
-Update with `codex plugin marketplace upgrade ask-pro`, then restart Codex.
-Both installs run the same bundled launcher and share the same state.
+This route needs Git and npm. The plugin's cached runner downloads pnpm, builds
+outside the plugin cache, and keeps the installed snapshot unchanged. If
+`ask-pro` is not on `PATH`, the skill uses that runner.
 
-You need Node.js 24+, npm, Chrome, and a ChatGPT account with Pro access. The
-browser runtime is developed and tested on Windows; other operating systems
-need validation.
+Update with `codex plugin marketplace upgrade ask-pro`, then restart Codex to
+load the updated skill.
+
+### Skills CLI (Codex and other supported agents)
+
+Install the skill and its standalone CLI separately:
 
-**Upgrading from an earlier version:** ask-pro state moved from
-`~/.codex/state/ask-pro` to `~/.agents/state/ask-pro`. Before the first run
-after upgrading, and while no ask-pro run is active, copy your signed-in browser
-state once:
+```powershell
+npx skills add JJLiebig/ask-pro
+npm install --global ask-pro
+```
+
+The [skills CLI](https://github.com/vercel-labs/skills) installs the skill in
+the current project by default. Add `-g` for a user-wide skill or `-a codex`
+to select Codex; it supports other agents too. The npm CLI runs without Codex's
+plugin cache.
+
+Update both parts:
 
 ```powershell
-New-Item -ItemType Directory -Force "$HOME\.agents\state" | Out-Null
-Copy-Item -Recurse "$HOME\.codex\state\ask-pro" "$HOME\.agents\state\ask-pro"
+npx skills update
+npm update --global ask-pro
 ```
 
+The browser runtime is developed and tested on Windows. Other operating systems
+need validation.
+
 ## Browser and session state
 
 ask-pro never asks for, types, reads, or logs passwords, MFA codes, recovery
@@ -46,9 +54,10 @@ codes, session cookies, or raw auth tokens. A new browser profile may need one
 manual ChatGPT login. On Windows, ordinary managed Chrome runs start minimized
 and are hidden; login and recovery restore the window for human action.
 
-ask-pro keeps its state in `~/.agents/state/ask-pro/`: the persistent browser
-profile in `browser-profile/` and the builds of the installed skill in
-`runtimes/`. Set `ASK_PRO_STATE_DIR` to use a different folder.
+The persistent profile lives at `$CODEX_HOME/state/ask-pro/browser-profile`, or
+`~/.codex/state/ask-pro/browser-profile` when `CODEX_HOME` is unset. Existing
+legacy profiles are migrated on first use; see [Windows notes](docs/windows-work.md)
+for copy and recovery details.
 
 Project sessions live under `.ask-pro/sessions/<id>/`. Add `.ask-pro/` to your
 project's `.gitignore`. At each invocation, ask-pro deletes entire session
@@ -56,9 +65,7 @@ directories at least seven days old, regardless of state.
 
 ## Use
 
-Agents run ask-pro through the installed skill, as
-`node <skill-folder>/scripts/ask-pro.mjs`; `ask-pro` below stands for that
-command. Ask for a recoverable repo consult:
+Ask for a recoverable repo consult:
 
 ```powershell
 ask-pro --no-temporary --prompt-file question.md --files src --files tests
@@ -79,7 +86,7 @@ ask-pro --harvest <session-id>
 
 Use `ask-pro --help` for the full CLI. For multiline prompts, use
 `--prompt-file`. Prefer `--no-temporary` when recovery matters; `--temporary`
-requires Temporary Chat. The [skill](SKILL.md) has agent guidance.
+requires Temporary Chat. The [skill](skills/ask-pro/SKILL.md) has agent guidance.
 
 When Pro asks native questions, ask-pro returns `awaiting_answers`, prints each
 question and its numbered choices, and saves `QUESTIONS.json`. The calling agent
@@ -147,8 +154,8 @@ pnpm run format:check
 pnpm pack --dry-run
 ```
 
-To try local changes as an installed skill, run
-`npx skills add <path-to-checkout> -g`. Live browser tests are opt-in; see
+After changing plugin files, run `pnpm run plugin:refresh` and restart Codex.
+Do not edit the installed plugin cache. Live browser tests are opt-in; see
 [manual tests](docs/manual-tests.md).
 
 After the build matrix passes on `main`, [CI](.github/workflows/ci.yml) publishes

package/dist/src/ask-pro/browserRunner.js

@@ -5,7 +5,7 @@ import { AssistantStoppedError, BrowserAutomationError } from "../browser/errors
 import { AssistantQuestionsError } from "../browser/actions/questions.js";
 import { readAskProQuestions, parseQuestionAnswers, writeAskProQuestions } from "./questions.js";
 import { GitHubConnectionRequiredError } from "../browser/actions/github.js";
-import { askProAgentIdForManagedBrowserProfileDir, askProBrowserProfileDirForAgentId, isAskProManagedBrowserProfileDir, resolveAskProAgentId, } from "../browser/profilePaths.js";
+import { askProAgentIdForLegacyBrowserProfileDir, askProAgentIdForManagedBrowserProfileDir, askProBrowserProfileDirForAgentId, ensureAskProBrowserProfileDir, isLegacyAskProManagedBrowserProfileDir, isAskProManagedBrowserProfileDir, resolveAskProAgentId, } from "../browser/profilePaths.js";
 import { runBrowserMode } from "../browserMode.js";
 import { closeTab } from "../browser/chromeLifecycle.js";
 import { resumeBrowserSession } from "../browser/reattach.js";
@@ -28,7 +28,7 @@ async function runAskProBrowserSessionWithLease({ cwd, sessionId, temporary: req
     const temporary = requestedTemporary ?? (sessionStatus.github ? false : undefined);
     const artifactsRequested = sessionStatus.artifacts === true;
     const agentId = agentIdOverride !== undefined ? agentIdOverride : resolveAskProAgentId();
-    const browserProfile = browserProfileDir ?? askProBrowserProfileDirForAgentId(agentId);
+    const browserProfile = browserProfileDir ?? (await ensureAskProBrowserProfileDir(agentId));
     const metadata = await readBrowserMetadata(paths.browser).catch(() => null);
     const chatgptUrl = chatgptUrlOverride ??
         (temporary === true
@@ -317,7 +317,7 @@ async function resumeAskProBrowserSessionWithLease({ cwd, sessionId, temporary,
         : effectiveTemporary === false
             ? ASK_PRO_CHATGPT_URL
             : (metadata.url ?? ASK_PRO_TEMPORARY_CHATGPT_URL);
-    const fallbackProfile = resolveResumeBrowserProfile(metadata);
+    const fallbackProfile = await resolveResumeBrowserProfile(metadata);
     if (sessionStatus.status === "NEEDS_GITHUB_CONNECTION" ||
         (sessionStatus.github && metadata.runtime?.githubCheckPending === true)) {
         await closeSessionBrowserTab(cwd, sessionId, logger);
@@ -716,26 +716,41 @@ async function writeTerminalBrowserMetadata(cwd, sessionId, status, reason) {
         },
     });
 }
-function resolveResumeBrowserProfile(metadata) {
+async function resolveResumeBrowserProfile(metadata) {
     const agentProfile = resolveStoredAgentProfile(metadata.agentId);
     const profileDir = metadata.profileDir;
     const profileAgentId = profileDir ? askProAgentIdForManagedBrowserProfileDir(profileDir) : null;
+    const legacyAgentId = profileDir ? askProAgentIdForLegacyBrowserProfileDir(profileDir) : null;
     if (profileAgentId && profileAgentId !== metadata.agentId) {
         throw new Error("Stored ask-pro agent profile does not match stored agent id.");
     }
+    if (legacyAgentId && legacyAgentId !== metadata.agentId) {
+        throw new Error("Stored ask-pro agent profile does not match stored agent id.");
+    }
     if (profileAgentId && agentProfile) {
         return profileDir;
     }
+    if (legacyAgentId && agentProfile) {
+        return ensureAskProBrowserProfileDir(metadata.agentId);
+    }
     if (profileDir &&
         !profileAgentId &&
+        !legacyAgentId &&
         !agentProfile &&
         isAskProManagedBrowserProfileDir(profileDir)) {
-        return askProBrowserProfileDirForAgentId(null);
+        return ensureAskProBrowserProfileDir(null);
+    }
+    if (profileDir &&
+        !profileAgentId &&
+        !legacyAgentId &&
+        !agentProfile &&
+        isLegacyAskProManagedBrowserProfileDir(profileDir)) {
+        return ensureAskProBrowserProfileDir(null);
     }
     if (profileDir) {
         throw new Error("Stored ask-pro profile path is invalid.");
     }
-    return askProBrowserProfileDirForAgentId(metadata.agentId);
+    return ensureAskProBrowserProfileDir(metadata.agentId);
 }
 function resolveStoredAgentProfile(agentId) {
     if (!agentId)

package/dist/src/browser/profilePaths.js

@@ -1,13 +1,144 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { acquireProfileRunLock, isBrowserProfileInUse, isProcessAlive, releaseProfileRunLock, } from "./profileState.js";
 const RESOLVED_AGENT_ID_PATTERN = /^[a-z0-9._-]+-[a-f0-9]{10}$/;
+const MIGRATION_MARKER = ".ask-pro-profile-migration";
 export function defaultAskProBrowserProfileDir() {
     return askProBrowserProfileDirForAgentId(null);
 }
 export function askProBrowserProfileDirForAgentId(agentId, env = process.env) {
     return profileDirUnder(askProStateDir(env), agentId);
 }
+export function legacyAskProBrowserProfileDirForAgentId(agentId, homeDir = os.homedir()) {
+    return profileDirUnder(path.join(homeDir, ".agents", "skills", "ask-pro"), agentId);
+}
+export async function ensureAskProBrowserProfileDir(agentId, options = {}) {
+    const target = askProBrowserProfileDirForAgentId(agentId, options.env);
+    const legacy = legacyAskProBrowserProfileDirForAgentId(agentId, options.homeDir);
+    const [targetExists, legacyExists] = await Promise.all([exists(target), exists(legacy)]);
+    if (targetExists && legacyExists) {
+        const recordedIdentity = await retainedLegacyIdentity(target);
+        if (recordedIdentity) {
+            const currentIdentity = await legacyProfileIdentity(legacy);
+            if (currentIdentity && sameLegacyIdentity(currentIdentity, recordedIdentity)) {
+                if (await waitForConcurrentMigration(target, legacy))
+                    return target;
+                if (await isBrowserProfileInUse(legacy)) {
+                    throw new Error("Legacy ask-pro browser profile is in use; retry after its browser run exits.");
+                }
+                return target;
+            }
+            throw new Error(`Both current and legacy ask-pro browser profiles exist; refusing to merge ${legacy} into ${target}.`);
+        }
+        if (await waitForConcurrentMigration(target, legacy))
+            return target;
+        if ((await exists(target)) && !(await exists(legacy)))
+            return target;
+        throw new Error(`Both current and legacy ask-pro browser profiles exist; refusing to merge ${legacy} into ${target}.`);
+    }
+    if (targetExists || !legacyExists)
+        return target;
+    if (await isBrowserProfileInUse(legacy)) {
+        throw new Error("Legacy ask-pro browser profile is in use; retry after its browser run exits.");
+    }
+    let migrationLock;
+    try {
+        migrationLock = await acquireProfileRunLock(legacy, {
+            timeoutMs: 300_000,
+            pollMs: 100,
+            requireExistingProfile: true,
+            staleLockMode: "fail",
+        });
+    }
+    catch (error) {
+        if ((await exists(target)) && !(await exists(legacy)))
+            return target;
+        throw new Error("Legacy ask-pro browser profile could not be claimed; retry after other browser runs exit.", { cause: error });
+    }
+    if (!migrationLock)
+        throw new Error("Could not claim the legacy ask-pro browser profile.");
+    let releasePath = migrationLock.path;
+    try {
+        if (await matchesRetainedLegacy(target, legacy))
+            return target;
+        if (await isBrowserProfileInUse(legacy, { ignoreLockId: migrationLock.lockId })) {
+            throw new Error("Legacy ask-pro browser profile is in use; retry after its browser run exits.");
+        }
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        let identityRequired = false;
+        try {
+            await fs.rename(legacy, target);
+            releasePath = path.join(target, path.basename(migrationLock.path));
+            return target;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EXDEV" && !isSharingDenied(error)) {
+                if ((await exists(target)) && !(await exists(legacy)))
+                    return target;
+                throw error;
+            }
+            identityRequired = code !== "EXDEV";
+        }
+        const legacyIdentity = await legacyProfileIdentity(legacy);
+        if (identityRequired && !legacyIdentity) {
+            throw new Error("Legacy ask-pro browser profile identity is unavailable; refusing to copy.");
+        }
+        const staging = `${target}.migrating-${process.pid}-${randomUUID()}`;
+        try {
+            await fs.cp(legacy, staging, { recursive: true, errorOnExist: true });
+            await fs.writeFile(path.join(staging, MIGRATION_MARKER), JSON.stringify({
+                pid: process.pid,
+                createdAt: Date.now(),
+                migrationLockId: migrationLock.lockId,
+                ...(legacyIdentity ? { legacyIdentity } : {}),
+            }));
+            await fs.rename(staging, target);
+            releasePath = path.join(target, path.basename(migrationLock.path));
+        }
+        catch (error) {
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+            if ((await exists(target)) && !(await exists(legacy)))
+                return target;
+            if (await matchesRetainedLegacy(target, legacy))
+                return target;
+            if (await waitForConcurrentMigration(target, legacy))
+                return target;
+            if ((await exists(target)) && !(await exists(legacy)))
+                return target;
+            throw error;
+        }
+        try {
+            await fs.rm(legacy, { recursive: true });
+        }
+        catch (error) {
+            await releaseProfileRunLock(migrationLock.path, migrationLock.lockId);
+            if (isSharingDenied(error) && legacyIdentity)
+                return target;
+            await fs.rm(path.join(target, MIGRATION_MARKER), { force: true });
+            if (isSharingDenied(error)) {
+                throw new Error("Legacy ask-pro browser profile could not be removed and has no reliable identity; refusing to retain it.", { cause: error });
+            }
+            throw error;
+        }
+        await fs.rm(path.join(target, MIGRATION_MARKER), { force: true });
+        return target;
+    }
+    finally {
+        await releaseProfileRunLock(releasePath, migrationLock.lockId);
+    }
+}
+export function askProAgentIdForLegacyBrowserProfileDir(profileDir) {
+    return agentIdForProfileDir(profileDir, path.join(os.homedir(), ".agents", "skills", "ask-pro"));
+}
+export function isLegacyAskProManagedBrowserProfileDir(profileDir) {
+    const resolved = normalizeProfilePath(profileDir);
+    if (resolved === normalizeProfilePath(legacyAskProBrowserProfileDirForAgentId(null)))
+        return true;
+    return askProAgentIdForLegacyBrowserProfileDir(profileDir) !== null;
+}
 function profileDirUnder(root, agentId) {
     if (!agentId)
         return path.join(root, "browser-profile");
@@ -45,8 +176,87 @@ function agentIdForProfileDir(profileDir, stateRoot) {
     return RESOLVED_AGENT_ID_PATTERN.test(agentId) ? agentId : null;
 }
 function askProStateDir(env = process.env) {
-    const override = env.ASK_PRO_STATE_DIR?.trim();
-    return override ? path.resolve(override) : path.join(os.homedir(), ".agents", "state", "ask-pro");
+    const codexHome = env.CODEX_HOME?.trim();
+    return path.join(codexHome ? path.resolve(codexHome) : path.join(os.homedir(), ".codex"), "state", "ask-pro");
+}
+async function exists(filePath) {
+    return fs
+        .stat(filePath)
+        .then(() => true)
+        .catch((error) => {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+}
+async function legacyProfileIdentity(profileDir) {
+    const info = await fs.stat(profileDir, { bigint: true }).catch(() => null);
+    if (!info?.isDirectory() || info.dev <= 0n || info.ino <= 0n || info.birthtimeNs <= 0n) {
+        return null;
+    }
+    return {
+        dev: info.dev.toString(),
+        ino: info.ino.toString(),
+        birthtimeNs: info.birthtimeNs.toString(),
+    };
+}
+async function retainedLegacyIdentity(target) {
+    const recorded = await fs
+        .readFile(path.join(target, MIGRATION_MARKER), "utf8")
+        .then((raw) => JSON.parse(raw).legacyIdentity)
+        .catch(() => null);
+    if (!recorded ||
+        ![recorded.dev, recorded.ino, recorded.birthtimeNs].every((value) => /^[1-9]\d*$/.test(value))) {
+        return null;
+    }
+    return recorded;
+}
+async function matchesRetainedLegacy(target, legacy) {
+    const [recorded, current] = await Promise.all([
+        retainedLegacyIdentity(target),
+        legacyProfileIdentity(legacy),
+    ]);
+    return recorded !== null && current !== null && sameLegacyIdentity(recorded, current);
+}
+function sameLegacyIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+}
+function isSharingDenied(error) {
+    return ["EACCES", "EBUSY", "EPERM"].includes(error.code ?? "");
+}
+async function waitForConcurrentMigration(target, legacy) {
+    const marker = path.join(target, MIGRATION_MARKER);
+    const owner = await fs
+        .readFile(marker, "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    if (!owner?.pid ||
+        !Number.isFinite(owner.pid) ||
+        !owner.createdAt ||
+        !Number.isFinite(owner.createdAt) ||
+        !owner.migrationLockId) {
+        return false;
+    }
+    while (isProcessAlive(owner.pid) &&
+        Date.now() - owner.createdAt < 300_000 &&
+        (await legacyHasMigrationLock(legacy, owner.migrationLockId))) {
+        if (!(await exists(legacy))) {
+            await fs.rm(marker, { force: true }).catch(() => undefined);
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    if (await exists(legacy))
+        return false;
+    await fs.rm(marker, { force: true }).catch(() => undefined);
+    return exists(target);
+}
+async function legacyHasMigrationLock(legacy, lockId) {
+    const activeLockId = await fs
+        .readFile(path.join(legacy, "ask-pro-automation.lock"), "utf8")
+        .then((raw) => JSON.parse(raw).lockId)
+        .catch(() => null);
+    return activeLockId === lockId;
 }
 export function resolveAskProAgentId(env = process.env) {
     const value = env.ASK_PRO_AGENT_ID;

package/dist/src/browser/profileState.js

@@ -168,6 +168,42 @@ function parseProfileRunLock(payload) {
         return null;
     }
 }
+export async function isBrowserProfileInUse(userDataDir, options = {}) {
+    const lockPath = path.join(userDataDir, ASK_PRO_PROFILE_LOCK_FILENAME);
+    let lockPayload;
+    try {
+        lockPayload = await readFile(lockPath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return true;
+        lockPayload = null;
+    }
+    let lock = parseProfileRunLock(lockPayload);
+    if (lockPayload !== null && !lock) {
+        await delay(200);
+        try {
+            lockPayload = await readFile(lockPath, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return true;
+            lockPayload = null;
+        }
+        lock = parseProfileRunLock(lockPayload);
+    }
+    if (lock && lock.lockId !== options.ignoreLockId && isProcessAlive(lock.pid))
+        return true;
+    const pid = await readChromePid(userDataDir);
+    const port = await readDevToolsPort(userDataDir);
+    const [owner, devTools] = await Promise.all([
+        isChromeUsingUserDataDir(userDataDir),
+        port ? verifyDevToolsReachable({ port, attempts: 1 }) : null,
+    ]);
+    if (owner === true || (pid && isProcessAlive(pid) && devTools?.ok))
+        return true;
+    return owner === null;
+}
 export async function acquireProfileRunLock(userDataDir, options) {
     const timeoutMs = options.timeoutMs;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -188,7 +224,12 @@ export async function acquireProfileRunLock(userDataDir, options) {
                 createdAt: new Date().toISOString(),
                 sessionId: options.sessionId,
             };
-            await mkdir(path.dirname(lockPath), { recursive: true });
+            if (options.requireExistingProfile) {
+                await stat(userDataDir);
+            }
+            else {
+                await mkdir(path.dirname(lockPath), { recursive: true });
+            }
             await writeFile(lockPath, JSON.stringify(payload), { encoding: "utf8", flag: "wx" });
             options.logger?.(`Acquired ask-pro profile lock at ${lockPath}`);
             return {
@@ -208,12 +249,18 @@ export async function acquireProfileRunLock(userDataDir, options) {
                 await delay(200);
                 existing = parseProfileRunLock(await readFile(lockPath, "utf8").catch(() => null));
                 if (!existing) {
+                    if (options.staleLockMode === "fail") {
+                        throw new Error("ask-pro profile lock is unreadable; refusing stale lock removal.");
+                    }
                     options.logger?.("ask-pro profile lock unreadable; deleting lockfile.");
                     await rm(lockPath, { force: true }).catch(() => undefined);
                     continue;
                 }
             }
             if (!existing || !isProcessAlive(existing.pid)) {
+                if (options.staleLockMode === "fail") {
+                    throw new Error("ask-pro profile lock owner is not alive; refusing stale lock removal.");
+                }
                 await rm(lockPath, { force: true }).catch(() => undefined);
                 continue;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-pro",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "Browser-backed ChatGPT Pro escalation for hard engineering questions.",
   "keywords": [
     "agents",
@@ -51,9 +51,10 @@
     "dist/src/browser/providers/chatgptDomProvider.js",
     "dist/src/browserMode.js",
     "dist/src/version.js",
+    "scripts/refresh-local-plugin.mjs",
+    "scripts/refresh-local-plugin.ps1",
     ".codex-plugin/plugin.json",
     "assets/ask-pro_logo.png",
-    "SKILL.md",
     "skills/ask-pro/SKILL.md",
     "README.md",
     "LICENSE"
@@ -71,6 +72,7 @@
     "format:diff": "oxfmt --write . && git --no-pager diff",
     "lint": "pnpm run typecheck && oxlint",
     "lint:fix": "oxlint --fix && pnpm run format",
+    "plugin:refresh": "pnpm run build && node scripts/refresh-local-plugin.mjs",
     "test": "pnpm run test:ask-pro",
     "test:ask-pro": "vitest run tests/ask-pro tests/browser",
     "test:coverage": "vitest run --coverage",

package/scripts/refresh-local-plugin.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = parseArgs(process.argv.slice(2));
+const pluginName = args.pluginName ?? "ask-pro";
+const codexHome = args.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
+const marketplacePath = args.marketplacePath ?? (await findCodexMarketplace(codexHome, pluginName));
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..");
+const marketplaceFile = path.resolve(marketplacePath);
+const marketplace = JSON.parse(await fs.readFile(marketplaceFile, "utf8"));
+const marketplaceName = String(marketplace.name ?? "").trim();
+if (!marketplaceName) {
+  throw new Error("Marketplace file must include a top-level name.");
+}
+
+const plugin = Array.isArray(marketplace.plugins)
+  ? marketplace.plugins.find((entry) => entry?.name === pluginName)
+  : null;
+if (!plugin) {
+  throw new Error(`Plugin '${pluginName}' was not found in ${marketplaceFile}.`);
+}
+if (plugin.source?.source === "local") {
+  const configuredSourcePath = plugin.source?.path;
+  if (typeof configuredSourcePath !== "string" || !configuredSourcePath.trim()) {
+    throw new Error(`Plugin '${pluginName}' local source must include a path.`);
+  }
+  const configuredSourceRoot = resolveConfiguredSourceRoot(configuredSourcePath, marketplaceFile);
+  if (!samePath(configuredSourceRoot, repoRoot)) {
+    throw new Error(
+      `Plugin '${pluginName}' marketplace path resolves to ${configuredSourceRoot}, not this checkout ${repoRoot}.`,
+    );
+  }
+} else if (plugin.source?.source !== "url") {
+  throw new Error(`Plugin '${pluginName}' must come from a local or URL marketplace source.`);
+}
+
+const manifestPath = path.join(repoRoot, ".codex-plugin", "plugin.json");
+const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+if (manifest.name !== pluginName) {
+  throw new Error(
+    `Plugin manifest name '${manifest.name}' does not match requested plugin '${pluginName}'.`,
+  );
+}
+
+const cacheRoot = path.resolve(codexHome, "plugins", "cache");
+const pluginCacheRoot = path.resolve(cacheRoot, marketplaceName, pluginName);
+const cacheVersion = plugin.source?.source === "local" ? "local" : manifest.version;
+if (typeof cacheVersion !== "string" || !cacheVersion.trim()) {
+  throw new Error(`Plugin '${pluginName}' manifest must include a version.`);
+}
+const targetRoot = path.resolve(pluginCacheRoot, cacheVersion);
+assertInside(
+  pluginCacheRoot,
+  cacheRoot,
+  "Resolved plugin cache path is outside Codex plugin cache",
+);
+
+const requiredDistEntry = path.join(repoRoot, "dist", "bin", "ask-pro-cli.js");
+if (!(await exists(requiredDistEntry))) {
+  throw new Error("dist is missing. Run `pnpm run build` before refreshing the plugin cache.");
+}
+const repoNodeModules = path.join(repoRoot, "node_modules");
+if (!(await exists(repoNodeModules))) {
+  throw new Error(
+    "node_modules is missing. Run `pnpm install` before refreshing the plugin cache.",
+  );
+}
+
+await removeNodeModulesLink(path.join(targetRoot, "node_modules"));
+await fs.rm(targetRoot, { recursive: true, force: true });
+await fs.mkdir(targetRoot, { recursive: true });
+
+for (const item of [
+  ".codex-plugin",
+  "assets",
+  "skills",
+  "references",
+  "README.md",
+  "LICENSE",
+  "package.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "dist",
+]) {
+  const source = path.join(repoRoot, item);
+  if (!(await exists(source))) continue;
+  await fs.cp(source, path.join(targetRoot, item), { recursive: true, force: true });
+}
+
+await fs.mkdir(path.join(targetRoot, "scripts"), { recursive: true });
+await fs.cp(
+  path.join(repoRoot, "scripts", "run-cached-cli.mjs"),
+  path.join(targetRoot, "scripts", "run-cached-cli.mjs"),
+  { force: true },
+);
+await fs.symlink(repoNodeModules, path.join(targetRoot, "node_modules"), "junction");
+
+console.log("Refreshed local Codex plugin cache:");
+console.log(`  source: ${repoRoot}`);
+console.log(`  target: ${targetRoot}`);
+console.log("");
+console.log("Restart or reload Codex to pick up refreshed plugin skills.");
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    if (!arg.startsWith("--") || !value || value.startsWith("--")) {
+      throw new Error(`Expected --name value argument, got '${arg}'.`);
+    }
+    i += 1;
+    if (arg === "--marketplace-path") result.marketplacePath = value;
+    else if (arg === "--codex-home") result.codexHome = value;
+    else if (arg === "--plugin-name") result.pluginName = value;
+    else throw new Error(`Unknown argument '${arg}'.`);
+  }
+  return result;
+}
+
+function assertInside(child, parent, message) {
+  const relative = path.relative(parent, child);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${message}: ${child}`);
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeNodeModulesLink(filePath) {
+  try {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) {
+      await fs.unlink(filePath);
+    }
+  } catch {
+    // Missing or non-removable links are handled by the full target cleanup.
+  }
+}
+
+async function findCodexMarketplace(codexHome, pluginName) {
+  const codexMarketplace = path.join(
+    codexHome,
+    ".tmp",
+    "marketplaces",
+    pluginName,
+    ".agents",
+    "plugins",
+    "marketplace.json",
+  );
+  if (await exists(codexMarketplace)) return codexMarketplace;
+  return path.join(os.homedir(), ".agents", "plugins", "marketplace.json");
+}
+
+function resolveConfiguredSourceRoot(sourcePath, marketplaceFile) {
+  const candidates = [
+    path.resolve(path.dirname(marketplaceFile), sourcePath),
+    path.resolve(os.homedir(), sourcePath),
+  ];
+  return candidates.find((candidate) => samePath(candidate, repoRoot)) ?? candidates[0];
+}
+
+function samePath(left, right) {
+  const a = path.resolve(left);
+  const b = path.resolve(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}

package/scripts/refresh-local-plugin.ps1

@@ -0,0 +1,93 @@
+param(
+  [string]$MarketplacePath = "",
+  [string]$CodexHome = $(if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME/.codex" }),
+  [string]$PluginName = "ask-pro"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-StrictPath([string]$Path) {
+  return [System.IO.Path]::GetFullPath((Resolve-Path -LiteralPath $Path).Path)
+}
+
+function Join-And-Normalize([string]$Base, [string[]]$Parts) {
+  return [System.IO.Path]::GetFullPath((Join-Path -Path $Base -ChildPath ([System.IO.Path]::Combine($Parts))))
+}
+
+$repoRoot = Resolve-StrictPath (Join-Path $PSScriptRoot "..")
+if ([string]::IsNullOrWhiteSpace($MarketplacePath)) {
+  $codexMarketplace = Join-And-Normalize $CodexHome @(".tmp", "marketplaces", $PluginName, ".agents", "plugins", "marketplace.json")
+  if (Test-Path -LiteralPath $codexMarketplace) {
+    $MarketplacePath = $codexMarketplace
+  } else {
+    $MarketplacePath = "$HOME/.agents/plugins/marketplace.json"
+  }
+}
+$marketplaceFile = Resolve-StrictPath $MarketplacePath
+$marketplace = Get-Content -LiteralPath $marketplaceFile -Raw | ConvertFrom-Json
+$marketplaceName = [string]$marketplace.name
+if ([string]::IsNullOrWhiteSpace($marketplaceName)) {
+  throw "Marketplace file must include a top-level name."
+}
+
+$plugin = @($marketplace.plugins) | Where-Object { $_.name -eq $PluginName } | Select-Object -First 1
+if (-not $plugin) {
+  throw "Plugin '$PluginName' was not found in $marketplaceFile."
+}
+if (($plugin.source.source -ne "local") -and ($plugin.source.source -ne "url")) {
+  throw "Plugin '$PluginName' must come from a local or URL marketplace source."
+}
+
+$sourceRoot = Resolve-StrictPath $repoRoot
+$manifestPath = Join-Path $sourceRoot ".codex-plugin/plugin.json"
+if (-not (Test-Path -LiteralPath $manifestPath)) {
+  throw "Missing plugin manifest at $manifestPath."
+}
+
+$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
+if ($manifest.name -ne $PluginName) {
+  throw "Plugin manifest name '$($manifest.name)' does not match requested plugin '$PluginName'."
+}
+
+$codexHomePath = [System.IO.Path]::GetFullPath($CodexHome)
+$cacheRoot = Join-And-Normalize $codexHomePath @("plugins", "cache")
+$pluginCacheRoot = Join-And-Normalize $cacheRoot @($marketplaceName, $PluginName)
+$cacheVersion = $(if ($plugin.source.source -eq "local") { "local" } else { [string]$manifest.version })
+if ([string]::IsNullOrWhiteSpace($cacheVersion)) {
+  throw "Plugin '$PluginName' manifest must include a version."
+}
+$targetRoot = Join-And-Normalize $pluginCacheRoot @($cacheVersion)
+
+$cacheRootWithSeparator = $cacheRoot.TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar
+if (-not $pluginCacheRoot.StartsWith($cacheRootWithSeparator, [System.StringComparison]::OrdinalIgnoreCase)) {
+  throw "Resolved plugin cache path is outside Codex plugin cache: $pluginCacheRoot"
+}
+
+if (Test-Path -LiteralPath $targetRoot) {
+  Remove-Item -LiteralPath $targetRoot -Recurse -Force
+}
+New-Item -ItemType Directory -Path $targetRoot -Force | Out-Null
+
+$itemsToCopy = @(
+  ".codex-plugin",
+  "skills",
+  "references",
+  "README.md",
+  "LICENSE",
+  "package.json",
+  "dist"
+)
+
+foreach ($item in $itemsToCopy) {
+  $source = Join-Path $sourceRoot $item
+  if (-not (Test-Path -LiteralPath $source)) {
+    continue
+  }
+  Copy-Item -LiteralPath $source -Destination $targetRoot -Recurse -Force
+}
+
+Write-Host "Refreshed local Codex plugin cache:"
+Write-Host "  source: $sourceRoot"
+Write-Host "  target: $targetRoot"
+Write-Host ""
+Write-Host "Restart or reload Codex to pick up refreshed plugin skills."

package/skills/ask-pro/SKILL.md

@@ -5,7 +5,232 @@ description: Escalate hard engineering questions to ChatGPT Pro through browser
 
 # $ask-pro
 
-This is the Codex plugin entry for ask-pro. The full instructions are in
-`SKILL.md` at the plugin root, two folders above this file. Read that file and
-follow it. Its `<skill-folder>` is the plugin root, so the launcher is
-`node <plugin-root>/scripts/ask-pro.mjs`.
+Use `$ask-pro` to ask ChatGPT Pro for a focused second opinion on hard engineering work.
+
+The calling agent still owns the work. Use Pro for judgment, architecture, risk review, or implementation planning when the decision is consequential enough to justify a browser run.
+
+## Trigger
+
+Use this skill when the user explicitly asks for `$ask-pro`, or when a second opinion would materially reduce risk for:
+
+- backend architecture
+- schema or data migrations
+- auth, sessions, permissions, or billing
+- queues, workers, idempotency, caching, scaling, or latency
+- production debugging and observability
+- ambiguous implementation paths where a second opinion would reduce risk
+
+Do not use it for trivial syntax fixes, formatting, obvious dependency updates, or small bugs with a clear cause.
+
+## Critical Reminders
+
+- Long waits are normal. ask-pro can take a super long time to run; do not
+  close or kill the browser window/run until at least 3 hours have passed unless
+  the CLI has completed, failed, or explicitly asks for human action.
+
+## Workflow
+
+When invoked:
+
+1. Inspect the repo and the relevant files.
+2. Identify the exact decision Pro should answer.
+3. For committed code on GitHub, prefer `--github` and give Pro the repository,
+   ref, relevant paths, and question. Let it retrieve the code instead of assembling
+   a source bundle. Add a small `--files` bundle only for uncommitted changes,
+   local-only evidence, or repository content the connection cannot access.
+4. Write the prompt yourself using the Prompt Shape below.
+5. Run the smallest useful command: `ask-pro --github "<prompt>"` for GitHub
+   evidence, or `ask-pro --no-temporary --files "<glob>" "<prompt>"` for a file bundle.
+   For multiline prompts, write a temporary prompt file and use
+   `ask-pro --no-temporary --prompt-file <path> --files "<glob>"`; do not rely
+   on shell multiline quoting.
+   If installed through the skills CLI and `ask-pro` is not on `PATH`, install
+   the standalone CLI from the [README](https://github.com/JJLiebig/ask-pro#skills-cli-codex-and-other-supported-agents)
+   first. For Codex plugin installs without `ask-pro` on `PATH`, use the cached
+   plugin runner. Locate it under the installed plugin cache,
+   usually
+   `~/.codex/plugins/cache/<marketplace-name>/ask-pro/<version>/scripts/run-cached-cli.mjs`,
+   then call it with:
+   `node <cached-runner> -- --cwd <target-repo-root> --no-temporary --prompt-file <path> --files "<repo-relative-glob>"`.
+   On Git marketplace installs, the first cached-runner call may bootstrap the
+   content-addressed runtime under `$CODEX_HOME/plugin-runtimes/ask-pro/` by
+   installing dependencies and building `dist`; wait for that to finish. The
+   installed plugin cache stays immutable.
+6. If auth is required, stop and ask the human to log in in the opened browser.
+7. Read the CLI's compact `ask_pro` record and run the emitted `resume` or
+   `harvest` command when that is the next action.
+8. Treat the answer as advisory; turn it into your own plan before editing code.
+
+`ask-pro` selects `Latest` when available, otherwise the highest numbered available
+GPT model, then `Pro` intelligence. Do not require a
+different dated model label or a separate thinking-effort control in the prompt
+or workflow.
+
+Fresh runs try ChatGPT Temporary Chat by default and automatically fall back to
+normal ChatGPT if the current account/UI does not expose Pro there. For repo
+advisories, large bundles, review rounds, or anything where recovery matters,
+prefer `--no-temporary` from the start. Add `--temporary` only when Temporary
+Chat is required and falling back would be wrong. Temporary Chat is less
+recoverable after browser/tab loss.
+
+On Windows, ordinary managed Chrome runs start minimized. First login,
+resume/recovery, and stale-auth paths stay visible or are restored for human
+action. Local managed Chrome guards browser input while Pro is answering.
+If login, MFA, a browser challenge, or incomplete-answer debugging needs human
+attention, ask-pro should restore or retain the browser and emit the next
+action.
+
+Do not set `ASK_PRO_AGENT_ID` for ordinary or concurrent use; the shared
+`ask-pro` browser profile under `$CODEX_HOME/state/ask-pro/` handles concurrent
+agents automatically. Set `ASK_PRO_AGENT_ID` only when explicitly testing an
+isolated profile or when the human requests a separate browser login. Use a
+stable reusable lowercase id like `review-t1`, not a one-off task slug, because
+each new id creates a new Chrome profile and may require the human to log in
+again. Example:
+`ASK_PRO_AGENT_ID=review-t1 ask-pro ...`.
+
+## Prompt Shape
+
+Assume Pro has no caller context or local checkout. Include each material fact and
+instruction once: the goal, current state, hard constraints, evidence, success
+criteria, and required output. Do not rely on the agent's conversation context, repo
+folklore, prior ask-pro runs, branch names, or unstated user preferences.
+Keep advisory design consults as plain answer requests. Start advisory prompts
+with:
+
+```text
+Return final Markdown only, with no preamble or implementation package.
+```
+
+The CLI wrapper already tells Pro to read `CONTEXT.zip` and call out missing or
+conflicting context. Do not repeat that instruction. Add task-specific output
+requirements only when needed. For risk or review work, ask Pro to rank
+findings by severity. For architecture or design consults, ask directly for the
+recommendation and tradeoffs.
+
+Use `--artifacts` only when the standard implementation package is needed. The
+wrapper supplies the zip name, standard files, and markdown fallback; add only
+task-specific deliverables not covered by that package. Keep advisory consults
+inline by default.
+Keep bundles focused: source files under review, focused tests, relevant docs,
+known recent changes, and validation status. Avoid whole-repo bundles unless the
+question is explicitly architectural.
+
+## Connected GitHub (optional)
+
+Prefer `--github` for remote repository evidence. It checks
+the connection before uploading or submitting, and defaults to normal ChatGPT.
+Do not require GitHub for file-based consults. Availability varies by account,
+workspace, model, and ChatGPT experience.
+
+If the CLI returns `needs_github_connection` / `connect_github_then_resume`,
+direct the human to the opened GitHub page in ask-pro's browser. They install the
+plugin if needed, complete sign-in, review permissions, and select repositories;
+organization approval may be needed. Wait for them to finish, then run the
+emitted resume command without adding `--github`. The requirement is saved with
+the session and checked again. Do not start a second session or submit through
+the browser yourself. Never collect GitHub credentials or automate authorization.
+
+If available, GitHub's **Allow read actions** permission can avoid read approval
+prompts. The human chooses that setting. It controls approval behavior, not the
+underlying permissions of a write-capable app; see
+[app permissions](https://help.openai.com/en/articles/20001495-managing-app-permissions-in-chatgpt).
+The live GitHub plugin advertises write capabilities despite the Help Center's
+read-only description. `--github` requests read-only work; it does not restrict
+the provider's permissions or prove that writes are impossible.
+
+If GitHub is already connected, proceed without a setup question or source-file
+bundle. For the consult, name the repository (`owner/repo`), relevant paths, and
+requested branch or commit in the prompt. Explicitly ask Pro
+to answer the specific question. The wrapper requests the connected GitHub app,
+read-only work, citations, the revision inspected, and access gaps. Do not
+infer repository access from ChatGPT login or a successful CLI exit.
+
+Keep `--files` for local/uncommitted changes, non-GitHub evidence, and snapshots
+that the app cannot retrieve. Distinguish
+uploaded evidence from GitHub evidence, and ask Pro to flag revision conflicts.
+If the app or requested revision is unavailable, offer a new consult with a
+focused file bundle and
+disclose that limitation. Do not silently switch away from Pro. The CLI submits
+text; it does not select an app in the composer or handle app approval prompts.
+Until a live run demonstrates retrieval, describe this as an available setup
+path, not a verified connection. Confirm material claims against the repo.
+
+## Output
+
+Normal `ask-pro` stdout is compact TOON-style telemetry. Use `state`, `action`,
+`resume`, and `harvest` to decide the next command. Browser progress may appear
+on stderr and can be ignored unless diagnosing a stuck run.
+
+`AWAITING_ANSWERS` / `answer_questions` means Pro is asking native interactive
+questions. Read the printed questions/options or `QUESTIONS.json`, answer from
+the caller's context, and ask the human only for decisions you cannot infer.
+Write UTF-8 JSON `{"requestId":"<request_id>","answers":[2,3,"free text"]}`
+with one answer per question in order, then run the emitted
+`ask-pro --resume <session-id> --answers <answers.json>` command. Numbers select
+1-based choices; strings enter the native free-text field. `--answers -` accepts
+piped JSON. Do not submit defaults or treat the question preamble as the answer.
+Repeat for further question rounds, then harvest the final answer normally.
+
+When present, use `profile`, `profile_path`, `chrome`, and `language` only as
+diagnostic hints. They tell you whether the run used the shared profile, an
+isolated agent profile, saved DevTools state, and English browser steering.
+When present, `conversation_url` is a recoverable non-temporary ChatGPT
+conversation URL.
+
+`ask-pro --harvest <session-id>` prints the raw markdown answer only for
+answer-bearing states such as `COMPLETED` or `HARVESTED`.
+For pending/incomplete sessions it prints compact status/action instead. For
+sessions run with `--artifacts`, any provided `ask-pro-response.zip` is
+extracted under the session's `pro-output/` directory and described in
+`PRO_OUTPUT_MANIFEST.json`. Inline-default sessions should not expect a zip.
+
+`INCOMPLETE_ANSWER` / `stopped_without_answer` means ChatGPT stopped without
+an answer after ask-pro attempted one automatic `continue`. Present the caller
+with the emitted resume command or a full retry of the original request in a new
+chat, and wait for their choice. Do not automatically resume or retry this state.
+An explicit `--resume` allows one more continuation attempt.
+
+`COMPLETED` means harvest now; the run browser may already be closed. If the
+state is `INCOMPLETE_ANSWER` / `preamble_without_artifacts`, do not treat
+`ANSWER.md` as final. Try resume/harvest if recoverable; otherwise rerun with
+`--no-temporary`, a tighter bundle, and a more direct prompt.
+
+## Commands
+
+```bash
+ask-pro "Review the async billing webhook migration plan and return an implementation plan."
+ask-pro --no-temporary --prompt-file question.md --files src --files tests
+ask-pro --github "In owner/repo at <commit>, inspect src/auth and explain token validation."
+ask-pro --temporary "Review this sensitive migration plan, and fail if Temporary Chat cannot use Pro."
+ask-pro --no-temporary "Review this in normal ChatGPT instead of Temporary Chat."
+ask-pro --prompt-file question.md --files .\src
+ask-pro --artifacts --prompt-file implementation-plan.md --files src
+ask-pro --files "src/api/stripe/**" --files "prisma/**" --files "src/lib/billing/**" \
+  "Review whether this Stripe webhook flow should use a queue or transactional outbox."
+ask-pro --dry-run "Prepare the Pro handoff but do not open the browser."
+ask-pro --resume <session-id>
+ask-pro --harvest <session-id>
+```
+
+If the binary is not on `PATH`, skills CLI installs need the standalone CLI from
+the README. Codex plugin installs can use the cached plugin runner. Do not run
+the plugin from a mutable development checkout; it may contain in-flight changes
+that have not been synced for agents.
+
+```bash
+node <cached-runner> -- --cwd /path/to/repo --no-temporary --prompt-file question.md --files src
+```
+
+In cached-runner fallback mode, `--files` must be inside `--cwd`. Use
+repo-relative `--files`; do not point at files outside the target repo cwd.
+
+## Safety
+
+Never ask for, read, store, type, or log passwords, MFA codes, recovery codes, session cookies, or raw auth tokens.
+
+Browser auth is human-controlled. Continue only after the human says the ChatGPT composer is visible.
+
+After submit, avoid interacting with any retained Chrome run window while Pro is
+thinking. ask-pro guards input after submit, but the safest agent behavior is to
+let the run finish or resume/harvest from CLI telemetry.

package/SKILL.md

@@ -1,229 +0,0 @@
----
-name: ask-pro
-description: Escalate hard engineering questions to ChatGPT Pro through browser automation with focused repo context. Use when an agent needs a stronger external review, architecture plan, migration strategy, production-debugging second opinion, or when the user explicitly asks to use $ask-pro.
----
-
-# $ask-pro
-
-Use `$ask-pro` to ask ChatGPT Pro for a focused second opinion on hard engineering work.
-
-The calling agent still owns the work. Use Pro for judgment, architecture, risk review, or implementation planning when the decision is consequential enough to justify a browser run.
-
-## Running ask-pro
-
-This skill folder contains ask-pro itself; nothing else needs installing. In
-the commands below, `ask-pro` stands for:
-
-```bash
-node <skill-folder>/scripts/ask-pro.mjs
-```
-
-`<skill-folder>` is the directory containing this `SKILL.md`. Run it from the
-target repo root. The first run after an install or update installs
-dependencies and builds, which can take a few minutes; wait for it. The CLI's
-emitted `resume` and `harvest` commands already contain the full launcher path;
-run them as printed. Node.js 24+, npm, and Chrome are required.
-
-## Trigger
-
-Use this skill when the user explicitly asks for `$ask-pro`, or when a second opinion would materially reduce risk for:
-
-- backend architecture
-- schema or data migrations
-- auth, sessions, permissions, or billing
-- queues, workers, idempotency, caching, scaling, or latency
-- production debugging and observability
-- ambiguous implementation paths where a second opinion would reduce risk
-
-Do not use it for trivial syntax fixes, formatting, obvious dependency updates, or small bugs with a clear cause.
-
-## Critical Reminders
-
-- Long waits are normal. ask-pro can take a super long time to run; do not
-  close or kill the browser window/run until at least 3 hours have passed unless
-  the CLI has completed, failed, or explicitly asks for human action.
-
-## Workflow
-
-When invoked:
-
-1. Inspect the repo and the relevant files.
-2. Identify the exact decision Pro should answer.
-3. For committed code on GitHub, prefer `--github` and give Pro the repository,
-   ref, relevant paths, and question. Let it retrieve the code instead of assembling
-   a source bundle. Add a small `--files` bundle only for uncommitted changes,
-   local-only evidence, or repository content the connection cannot access.
-4. Write the prompt yourself using the Prompt Shape below.
-5. Run the smallest useful command: `ask-pro --github "<prompt>"` for GitHub
-   evidence, or `ask-pro --no-temporary --files "<glob>" "<prompt>"` for a file bundle.
-   For multiline prompts, write a temporary prompt file and use
-   `ask-pro --no-temporary --prompt-file <path> --files "<glob>"`; do not rely
-   on shell multiline quoting.
-6. If auth is required, stop and ask the human to log in in the opened browser.
-7. Read the CLI's compact `ask_pro` record and run the emitted `resume` or
-   `harvest` command when that is the next action.
-8. Treat the answer as advisory; turn it into your own plan before editing code.
-
-`ask-pro` selects `Latest` when available, otherwise the highest numbered available
-GPT model, then `Pro` intelligence. Do not require a
-different dated model label or a separate thinking-effort control in the prompt
-or workflow.
-
-Fresh runs try ChatGPT Temporary Chat by default and automatically fall back to
-normal ChatGPT if the current account/UI does not expose Pro there. For repo
-advisories, large bundles, review rounds, or anything where recovery matters,
-prefer `--no-temporary` from the start. Add `--temporary` only when Temporary
-Chat is required and falling back would be wrong. Temporary Chat is less
-recoverable after browser/tab loss.
-
-On Windows, ordinary managed Chrome runs start minimized. First login,
-resume/recovery, and stale-auth paths stay visible or are restored for human
-action. Local managed Chrome guards browser input while Pro is answering.
-If login, MFA, a browser challenge, or incomplete-answer debugging needs human
-attention, ask-pro should restore or retain the browser and emit the next
-action.
-
-Do not set `ASK_PRO_AGENT_ID` for ordinary or concurrent use; the shared
-`ask-pro` browser profile under `~/.agents/state/ask-pro/` handles concurrent
-agents automatically. Set `ASK_PRO_AGENT_ID` only when explicitly testing an
-isolated profile or when the human requests a separate browser login. Use a
-stable reusable lowercase id like `review-t1`, not a one-off task slug, because
-each new id creates a new Chrome profile and may require the human to log in
-again. Example:
-`ASK_PRO_AGENT_ID=review-t1 ask-pro ...`.
-
-## Prompt Shape
-
-Assume Pro has no caller context or local checkout. Include each material fact and
-instruction once: the goal, current state, hard constraints, evidence, success
-criteria, and required output. Do not rely on the agent's conversation context, repo
-folklore, prior ask-pro runs, branch names, or unstated user preferences.
-Keep advisory design consults as plain answer requests. Start advisory prompts
-with:
-
-```text
-Return final Markdown only, with no preamble or implementation package.
-```
-
-The CLI wrapper already tells Pro to read `CONTEXT.zip` and call out missing or
-conflicting context. Do not repeat that instruction. Add task-specific output
-requirements only when needed. For risk or review work, ask Pro to rank
-findings by severity. For architecture or design consults, ask directly for the
-recommendation and tradeoffs.
-
-Use `--artifacts` only when the standard implementation package is needed. The
-wrapper supplies the zip name, standard files, and markdown fallback; add only
-task-specific deliverables not covered by that package. Keep advisory consults
-inline by default.
-Keep bundles focused: source files under review, focused tests, relevant docs,
-known recent changes, and validation status. Avoid whole-repo bundles unless the
-question is explicitly architectural.
-
-## Connected GitHub (optional)
-
-Prefer `--github` for remote repository evidence. It checks
-the connection before uploading or submitting, and defaults to normal ChatGPT.
-Do not require GitHub for file-based consults. Availability varies by account,
-workspace, model, and ChatGPT experience.
-
-If the CLI returns `needs_github_connection` / `connect_github_then_resume`,
-direct the human to the opened GitHub page in ask-pro's browser. They install the
-plugin if needed, complete sign-in, review permissions, and select repositories;
-organization approval may be needed. Wait for them to finish, then run the
-emitted resume command without adding `--github`. The requirement is saved with
-the session and checked again. Do not start a second session or submit through
-the browser yourself. Never collect GitHub credentials or automate authorization.
-
-If available, GitHub's **Allow read actions** permission can avoid read approval
-prompts. The human chooses that setting. It controls approval behavior, not the
-underlying permissions of a write-capable app; see
-[app permissions](https://help.openai.com/en/articles/20001495-managing-app-permissions-in-chatgpt).
-The live GitHub plugin advertises write capabilities despite the Help Center's
-read-only description. `--github` requests read-only work; it does not restrict
-the provider's permissions or prove that writes are impossible.
-
-If GitHub is already connected, proceed without a setup question or source-file
-bundle. For the consult, name the repository (`owner/repo`), relevant paths, and
-requested branch or commit in the prompt. Explicitly ask Pro
-to answer the specific question. The wrapper requests the connected GitHub app,
-read-only work, citations, the revision inspected, and access gaps. Do not
-infer repository access from ChatGPT login or a successful CLI exit.
-
-Keep `--files` for local/uncommitted changes, non-GitHub evidence, and snapshots
-that the app cannot retrieve. Distinguish
-uploaded evidence from GitHub evidence, and ask Pro to flag revision conflicts.
-If the app or requested revision is unavailable, offer a new consult with a
-focused file bundle and
-disclose that limitation. Do not silently switch away from Pro. The CLI submits
-text; it does not select an app in the composer or handle app approval prompts.
-Until a live run demonstrates retrieval, describe this as an available setup
-path, not a verified connection. Confirm material claims against the repo.
-
-## Output
-
-Normal `ask-pro` stdout is compact TOON-style telemetry. Use `state`, `action`,
-`resume`, and `harvest` to decide the next command. Browser progress may appear
-on stderr and can be ignored unless diagnosing a stuck run.
-
-`AWAITING_ANSWERS` / `answer_questions` means Pro is asking native interactive
-questions. Read the printed questions/options or `QUESTIONS.json`, answer from
-the caller's context, and ask the human only for decisions you cannot infer.
-Write UTF-8 JSON `{"requestId":"<request_id>","answers":[2,3,"free text"]}`
-with one answer per question in order, then run the emitted
-`ask-pro --resume <session-id> --answers <answers.json>` command. Numbers select
-1-based choices; strings enter the native free-text field. `--answers -` accepts
-piped JSON. Do not submit defaults or treat the question preamble as the answer.
-Repeat for further question rounds, then harvest the final answer normally.
-
-When present, use `profile`, `profile_path`, `chrome`, and `language` only as
-diagnostic hints. They tell you whether the run used the shared profile, an
-isolated agent profile, saved DevTools state, and English browser steering.
-When present, `conversation_url` is a recoverable non-temporary ChatGPT
-conversation URL.
-
-`ask-pro --harvest <session-id>` prints the raw markdown answer only for
-answer-bearing states such as `COMPLETED` or `HARVESTED`.
-For pending/incomplete sessions it prints compact status/action instead. For
-sessions run with `--artifacts`, any provided `ask-pro-response.zip` is
-extracted under the session's `pro-output/` directory and described in
-`PRO_OUTPUT_MANIFEST.json`. Inline-default sessions should not expect a zip.
-
-`INCOMPLETE_ANSWER` / `stopped_without_answer` means ChatGPT stopped without
-an answer after ask-pro attempted one automatic `continue`. Present the caller
-with the emitted resume command or a full retry of the original request in a new
-chat, and wait for their choice. Do not automatically resume or retry this state.
-An explicit `--resume` allows one more continuation attempt.
-
-`COMPLETED` means harvest now; the run browser may already be closed. If the
-state is `INCOMPLETE_ANSWER` / `preamble_without_artifacts`, do not treat
-`ANSWER.md` as final. Try resume/harvest if recoverable; otherwise rerun with
-`--no-temporary`, a tighter bundle, and a more direct prompt.
-
-## Commands
-
-```bash
-ask-pro "Review the async billing webhook migration plan and return an implementation plan."
-ask-pro --no-temporary --prompt-file question.md --files src --files tests
-ask-pro --github "In owner/repo at <commit>, inspect src/auth and explain token validation."
-ask-pro --temporary "Review this sensitive migration plan, and fail if Temporary Chat cannot use Pro."
-ask-pro --no-temporary "Review this in normal ChatGPT instead of Temporary Chat."
-ask-pro --prompt-file question.md --files .\src
-ask-pro --artifacts --prompt-file implementation-plan.md --files src
-ask-pro --files "src/api/stripe/**" --files "prisma/**" --files "src/lib/billing/**" \
-  "Review whether this Stripe webhook flow should use a queue or transactional outbox."
-ask-pro --dry-run "Prepare the Pro handoff but do not open the browser."
-ask-pro --resume <session-id>
-ask-pro --harvest <session-id>
-```
-
-`--files` must be inside the target repo. Use repo-relative paths.
-
-## Safety
-
-Never ask for, read, store, type, or log passwords, MFA codes, recovery codes, session cookies, or raw auth tokens.
-
-Browser auth is human-controlled. Continue only after the human says the ChatGPT composer is visible.
-
-After submit, avoid interacting with any retained Chrome run window while Pro is
-thinking. ask-pro guards input after submit, but the safest agent behavior is to
-let the run finish or resume/harvest from CLI telemetry.