@steipete/oracle 0.4.5 → 0.5.1

package/README.md

@@ -11,7 +11,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"></a>
 </p>
 
-Oracle bundles your prompt and files so another AI can answer with real context. It speaks GPT-5.1 Pro (default), GPT-5.1 Codex (API-only), GPT-5.1, Gemini 3 Pro, Claude Sonnet 4.5, Claude Opus 4.1, and more—and it can ask one or multiple models in a single run. Browser automation exists but is **experimental**; prefer API or `--copy` and paste into ChatGPT yourself.
+Oracle bundles your prompt and files so another AI can answer with real context. It speaks GPT-5.1 Pro (default), GPT-5.1 Codex (API-only), GPT-5.1, Gemini 3 Pro, Claude Sonnet 4.5, Claude Opus 4.1, and more—and it can ask one or multiple models in a single run. Browser automation is available; API remains the most reliable path, and `--copy` is an easy manual fallback.
 
 ## Quick start
 
@@ -30,7 +30,7 @@ npx @steipete/oracle -p "Cross-check the data layer assumptions" --models gpt-5.
 # Preview without spending tokens
 npx @steipete/oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
 
-# Experimental browser run (no API key, will open ChatGPT)
+# Browser run (no API key, will open ChatGPT)
 npx @steipete/oracle --engine browser -p "Walk through the UI smoke test" --file "src/**/*.ts"
 
 # Sessions (list and replay)
@@ -41,14 +41,14 @@ npx @steipete/oracle session <id> --render
 npx @steipete/oracle
 ```
 
-Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser is stable on macOS, works on Linux with `--browser-chrome-path/--browser-cookie-path`, and is partial/experimental on Windows.
+Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser is stable on macOS and works on Linux and Windows. On Linux pass `--browser-chrome-path/--browser-cookie-path` if detection fails; on Windows prefer `--browser-manual-login` or inline cookies if decryption is blocked.
 
 ## Integration
 
 **CLI**
 - API mode expects API keys in your environment: `OPENAI_API_KEY` (GPT-5.x), `GEMINI_API_KEY` (Gemini 3 Pro), `ANTHROPIC_API_KEY` (Claude Sonnet 4.5 / Opus 4.1).
 - Prefer API mode or `--copy` + manual paste; browser automation is experimental.
-- Browser support: stable on macOS; works on Linux with `--browser-chrome-path/--browser-cookie-path`; Windows is partial/experimental.
+- Browser support: stable on macOS; works on Linux (add `--browser-chrome-path/--browser-cookie-path` when needed) and Windows (manual-login or inline cookies recommended when app-bound cookies block decryption).
 - Remote browser service: `oracle serve` on a signed-in host; clients use `--remote-host/--remote-token`.
 - AGENTS.md/CLAUDE.md:
   ```
@@ -78,7 +78,7 @@ npx -y @steipete/oracle oracle-mcp
 ## Highlights
 
 - Bundle once, reuse anywhere (API or experimental browser).
-- Multi-model API runs with aggregated cost/usage.
+- Multi-model API runs with aggregated cost/usage, including OpenRouter IDs alongside first-party models.
 - Render/copy bundles for manual paste into ChatGPT when automation is blocked.
 - GPT‑5 Pro API runs detach by default; reattach via `oracle session <id>` / `oracle status` or block with `--wait`.
 - Azure endpoints supported via `--azure-endpoint/--azure-deployment/--azure-api-version` or `AZURE_OPENAI_*` envs.
@@ -93,10 +93,11 @@ npx -y @steipete/oracle oracle-mcp
 | `-p, --prompt <text>` | Required prompt. |
 | `-f, --file <paths...>` | Attach files/dirs (globs + `!` excludes). |
 | `-e, --engine <api\|browser>` | Choose API or browser (browser is experimental). |
-| `-m, --model <name>` | `gpt-5.1-pro` (default), `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex` (API-only), `gemini-3-pro`, `claude-4.5-sonnet`, `claude-4.1-opus`, plus documented aliases. |
-| `--models <list>` | Comma-separated API models for multi-model runs. |
-| `--base-url <url>` | Point API runs at LiteLLM/Azure/etc. |
+| `-m, --model <name>` | Built-ins (`gpt-5.1-pro` default, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gemini-3-pro`, `claude-4.5-sonnet`, `claude-4.1-opus`) plus any OpenRouter id (e.g., `minimax/minimax-m2`, `openai/gpt-4o-mini`). |
+| `--models <list>` | Comma-separated API models (mix built-ins and OpenRouter ids) for multi-model runs. |
+| `--base-url <url>` | Point API runs at LiteLLM/Azure/OpenRouter/etc. |
 | `--chatgpt-url <url>` | Target a ChatGPT workspace/folder (browser). |
+| `--browser-port <port>` | Pin the Chrome DevTools port (WSL/Windows firewall helper). |
 | `--browser-inline-cookies[(-file)] <payload|path>` | Supply cookies without Chrome/Keychain (browser). |
 | `--browser-timeout`, `--browser-input-timeout` | Control overall/browser input timeouts (supports h/m/s/ms). |
 | `--render`, `--copy` | Print and/or copy the assembled markdown bundle. |
@@ -152,8 +153,9 @@ oracle status --clear --hours 168
 ## More docs
 - Browser mode & forks: [docs/browser-mode.md](docs/browser-mode.md) (includes `oracle serve` remote service), [docs/chromium-forks.md](docs/chromium-forks.md), [docs/linux.md](docs/linux.md)
 - MCP: [docs/mcp.md](docs/mcp.md)
-- OpenAI/Azure endpoints: [docs/openai-endpoints.md](docs/openai-endpoints.md)
+- OpenAI/Azure/OpenRouter endpoints: [docs/openai-endpoints.md](docs/openai-endpoints.md), [docs/openrouter.md](docs/openrouter.md)
 - Manual smokes: [docs/manual-tests.md](docs/manual-tests.md)
+- Testing: [docs/testing.md](docs/testing.md)
 
 If you’re looking for an even more powerful context-management tool, check out https://repoprompt.com  
 Name inspired by: https://ampcode.com/news/oracle

package/dist/bin/oracle-cli.js

@@ -15,7 +15,8 @@ import { shouldRequirePrompt } from '../src/cli/promptRequirement.js';
 import chalk from 'chalk';
 import { sessionStore, pruneOldSessions } from '../src/sessionStore.js';
 import { DEFAULT_MODEL, MODEL_CONFIGS, readFiles, estimateRequestTokens, buildRequestBody } from '../src/oracle.js';
-import { CHATGPT_URL, normalizeChatgptUrl } from '../src/browserMode.js';
+import { isKnownModel } from '../src/oracle/modelResolver.js';
+import { CHATGPT_URL } from '../src/browserMode.js';
 import { createRemoteBrowserExecutor } from '../src/remote/client.js';
 import { applyHelpStyling } from '../src/cli/help.js';
 import { collectPaths, collectModelList, parseFloatOption, parseIntOption, parseSearchOption, usesDefaultStatusFilters, resolvePreviewMode, normalizeModelOption, normalizeBaseUrl, resolveApiModel, inferModelFromLabel, parseHeartbeatOption, parseTimeoutOption, mergePathLikeOptions, } from '../src/cli/options.js';
@@ -41,6 +42,7 @@ import { runDryRunSummary, runBrowserPreview } from '../src/cli/dryRun.js';
 import { launchTui } from '../src/cli/tui/index.js';
 import { resolveNotificationSettings, deriveNotificationSettingsFromMetadata, } from '../src/cli/notifier.js';
 import { loadUserConfig } from '../src/config.js';
+import { applyBrowserDefaultsFromConfig } from '../src/cli/browserDefaults.js';
 import { shouldBlockDuplicatePrompt } from '../src/cli/duplicatePromptGuard.js';
 const VERSION = getCliVersion();
 const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
@@ -160,10 +162,14 @@ program
     .addOption(new Option('--browser-url <url>', `Alias for --chatgpt-url (default ${CHATGPT_URL}).`).hideHelp())
     .addOption(new Option('--browser-timeout <ms|s|m>', 'Maximum time to wait for an answer (default 1200s / 20m).').hideHelp())
     .addOption(new Option('--browser-input-timeout <ms|s|m>', 'Maximum time to wait for the prompt textarea (default 30s).').hideHelp())
+    .addOption(new Option('--browser-port <port>', 'Use a fixed Chrome DevTools port (helpful on WSL firewalls).')
+    .argParser(parseIntOption))
+    .addOption(new Option('--browser-debug-port <port>', '(alias) Use a fixed Chrome DevTools port.').argParser(parseIntOption).hideHelp())
     .addOption(new Option('--browser-cookie-names <names>', 'Comma-separated cookie allowlist for sync.').hideHelp())
     .addOption(new Option('--browser-inline-cookies <jsonOrBase64>', 'Inline cookies payload (JSON array or base64-encoded JSON).').hideHelp())
     .addOption(new Option('--browser-inline-cookies-file <path>', 'Load inline cookies from file (JSON or base64 JSON).').hideHelp())
     .addOption(new Option('--browser-no-cookie-sync', 'Skip copying cookies from Chrome.').hideHelp())
+    .addOption(new Option('--browser-manual-login', 'Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login.').hideHelp())
     .addOption(new Option('--browser-headless', 'Launch Chrome in headless mode.').hideHelp())
     .addOption(new Option('--browser-hide-window', 'Hide the Chrome window after launch (macOS headful only).').hideHelp())
     .addOption(new Option('--browser-keep-browser', 'Keep Chrome running after completion.').hideHelp())
@@ -363,7 +369,7 @@ function getBrowserConfigFromMetadata(metadata) {
 async function runRootCommand(options) {
     if (process.env.ORACLE_FORCE_TUI === '1') {
         await sessionStore.ensureStorage();
-        await launchTui({ version: VERSION });
+        await launchTui({ version: VERSION, printIntro: false });
         return;
     }
     const userConfig = (await loadUserConfig()).config;
@@ -417,7 +423,7 @@ async function runRootCommand(options) {
     }
     if (userCliArgs.length === 0) {
         if (tuiEnabled()) {
-            await launchTui({ version: VERSION });
+            await launchTui({ version: VERSION, printIntro: false });
             return;
         }
         console.log(chalk.yellow('No prompt or subcommand supplied. See `oracle --help` for usage.'));
@@ -528,7 +534,9 @@ async function runRootCommand(options) {
     const resolvedModel = normalizedMultiModels[0] ?? (isGemini ? resolveApiModel(cliModelArg) : resolvedModelCandidate);
     const effectiveModelId = resolvedModel.startsWith('gemini')
         ? resolveGeminiModelId(resolvedModel)
-        : MODEL_CONFIGS[resolvedModel]?.apiModel ?? resolvedModel;
+        : isKnownModel(resolvedModel)
+            ? MODEL_CONFIGS[resolvedModel].apiModel ?? resolvedModel
+            : resolvedModel;
     const resolvedBaseUrl = normalizeBaseUrl(options.baseUrl ?? (isClaude ? process.env.ANTHROPIC_BASE_URL : process.env.OPENAI_BASE_URL));
     const { models: _rawModels, ...optionsWithoutModels } = options;
     const resolvedOptions = { ...optionsWithoutModels, model: resolvedModel };
@@ -566,7 +574,7 @@ async function runRootCommand(options) {
             throw new Error('Prompt is required when using --render-markdown or --copy-markdown.');
         }
         const bundle = await buildMarkdownBundle({ prompt: options.prompt, file: options.file, system: options.system }, { cwd: process.cwd() });
-        const modelConfig = MODEL_CONFIGS[resolvedModel];
+        const modelConfig = isKnownModel(resolvedModel) ? MODEL_CONFIGS[resolvedModel] : MODEL_CONFIGS['gpt-5.1'];
         const requestBody = buildRequestBody({
             modelConfig,
             systemPrompt: bundle.systemPrompt,
@@ -658,7 +666,8 @@ async function runRootCommand(options) {
     if (options.file && options.file.length > 0) {
         await readFiles(options.file, { cwd: process.cwd() });
     }
-    applyBrowserDefaultsFromConfig(options, userConfig);
+    const getSource = (key) => program.getOptionValueSource?.(key) ?? undefined;
+    applyBrowserDefaultsFromConfig(options, userConfig, getSource);
     const notifications = resolveNotificationSettings({
         cliNotify: options.notify,
         cliNotifySound: options.notifySound,
@@ -878,6 +887,7 @@ function printDebugHelp(cliName) {
         ['--browser-timeout <ms|s|m>', 'Cap total wait time for the assistant response.'],
         ['--browser-input-timeout <ms|s|m>', 'Cap how long we wait for the composer textarea.'],
         ['--browser-no-cookie-sync', 'Skip copying cookies from your main profile.'],
+        ['--browser-manual-login', 'Skip cookie copy; reuse a persistent automation profile and log in manually.'],
         ['--browser-headless', 'Launch Chrome in headless mode.'],
         ['--browser-hide-window', 'Hide the Chrome window (macOS headful only).'],
         ['--browser-keep-browser', 'Leave Chrome running after completion.'],
@@ -899,48 +909,6 @@ function resolveWaitFlag({ waitFlag, noWaitFlag, model, engine, }) {
         return false;
     return defaultWaitPreference(model, engine);
 }
-function applyBrowserDefaultsFromConfig(options, config) {
-    const browser = config.browser;
-    if (!browser)
-        return;
-    const source = (key) => program.getOptionValueSource?.(key);
-    const configuredChatgptUrl = browser.chatgptUrl ?? browser.url;
-    if (source('chatgptUrl') === 'default' && configuredChatgptUrl !== undefined) {
-        try {
-            options.chatgptUrl = normalizeChatgptUrl(configuredChatgptUrl ?? '', CHATGPT_URL);
-        }
-        catch (error) {
-            throw error instanceof Error ? error : new Error(String(error));
-        }
-    }
-    if (source('browserChromeProfile') === 'default' && browser.chromeProfile !== undefined) {
-        options.browserChromeProfile = browser.chromeProfile ?? undefined;
-    }
-    if (source('browserChromePath') === 'default' && browser.chromePath !== undefined) {
-        options.browserChromePath = browser.chromePath ?? undefined;
-    }
-    if (source('browserCookiePath') === 'default' && browser.chromeCookiePath !== undefined) {
-        options.browserCookiePath = browser.chromeCookiePath ?? undefined;
-    }
-    if (source('browserUrl') === 'default' && browser.url !== undefined) {
-        options.browserUrl = browser.url;
-    }
-    if (source('browserTimeout') === 'default' && typeof browser.timeoutMs === 'number') {
-        options.browserTimeout = String(browser.timeoutMs);
-    }
-    if (source('browserInputTimeout') === 'default' && typeof browser.inputTimeoutMs === 'number') {
-        options.browserInputTimeout = String(browser.inputTimeoutMs);
-    }
-    if (source('browserHeadless') === 'default' && browser.headless !== undefined) {
-        options.browserHeadless = browser.headless;
-    }
-    if (source('browserHideWindow') === 'default' && browser.hideWindow !== undefined) {
-        options.browserHideWindow = browser.hideWindow;
-    }
-    if (source('browserKeepBrowser') === 'default' && browser.keepBrowser !== undefined) {
-        options.browserKeepBrowser = browser.keepBrowser;
-    }
-}
 program.action(async function () {
     const options = this.optsWithGlobals();
     await runRootCommand(options);

package/dist/scripts/agent-send.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+// @ts-nocheck
+/**
+ * Lightweight helper to send a one-off message to a tmux-based agent session.
+ *
+ * Usage:
+ *   bun scripts/agent-send.ts --session claude-haiku -- "/model"
+ *
+ * Options:
+ *   --session NAME             Target tmux session (or session:window.pane)
+ *   --entry single|double|none How many Enter keys to send (default single)
+ *   --escape                   Send ESC before typing (to interrupt/resume)
+ *   --wait-ms N                Extra wait (ms) after typing before Enter
+ */
+import { spawnSync } from 'node:child_process';
+import { sleepSync } from 'bun';
+function usage(message) {
+    if (message) {
+        console.error(`Error: ${message}`);
+    }
+    console.error(`\
+Usage: bun scripts/agent-send.ts --session <name[:window[.pane]]> [--entry single|double|none] [--escape] [--wait-ms N] -- "<message>"
+
+Examples:
+  bun scripts/agent-send.ts --session claude-haiku -- "/model"
+  bun scripts/agent-send.ts --session ma-worker-1 --escape --entry double -- "Continue and focus on API routes"
+`);
+    process.exit(1);
+}
+function parseArgs(argv) {
+    let session;
+    let entry = 'single';
+    let shouldEscape = false;
+    let waitMs = 400;
+    const literalSeparator = argv.indexOf('--');
+    const optionPart = literalSeparator === -1 ? argv : argv.slice(0, literalSeparator);
+    const literalPart = literalSeparator === -1 ? [] : argv.slice(literalSeparator + 1);
+    for (let i = 0; i < optionPart.length; i += 1) {
+        const token = optionPart[i];
+        if (!token.startsWith('--')) {
+            usage(`Unexpected argument: ${token}`);
+        }
+        const key = token.slice(2);
+        switch (key) {
+            case 'session': {
+                const value = optionPart[i + 1];
+                if (!value)
+                    usage('--session requires a value');
+                session = value;
+                i += 1;
+                break;
+            }
+            case 'entry': {
+                const value = optionPart[i + 1];
+                if (value !== 'single' && value !== 'double' && value !== 'none') {
+                    usage(`Unknown entry mode: ${value}`);
+                }
+                entry = value;
+                i += 1;
+                break;
+            }
+            case 'escape': {
+                shouldEscape = true;
+                break;
+            }
+            case 'wait-ms': {
+                const value = optionPart[i + 1];
+                if (!value || Number.isNaN(Number.parseInt(value, 10))) {
+                    usage('--wait-ms requires an integer value');
+                }
+                waitMs = Number.parseInt(value, 10);
+                i += 1;
+                break;
+            }
+            default:
+                usage(`Unknown option: --${key}`);
+        }
+    }
+    const message = literalPart.join(' ').trim();
+    if (!session)
+        usage('Missing --session');
+    if (!message)
+        usage('Missing message (provide text after -- separator)');
+    return { session, entry, escape: shouldEscape, waitMs, message };
+}
+function runTmux(args, allowFailure = false) {
+    const result = spawnSync('tmux', args, { encoding: 'utf8' });
+    if (result.error) {
+        if (allowFailure)
+            return '';
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        if (allowFailure)
+            return result.stderr?.trim() ?? '';
+        throw new Error(`tmux ${args.join(' ')} failed: ${result.stderr?.trim()}`);
+    }
+    return result.stdout?.trimEnd() ?? '';
+}
+function ensureSession(target) {
+    const session = target.split(':')[0] ?? target;
+    const result = spawnSync('tmux', ['has-session', '-t', session]);
+    if (result.status !== 0) {
+        usage(`tmux session '${session}' not found. Start it first (e.g., tmux new-session -s ${session} ...)`);
+    }
+}
+function sendMessage(options) {
+    ensureSession(options.session);
+    if (options.escape) {
+        runTmux(['send-keys', '-t', options.session, 'Escape'], true);
+        sleepSync(200);
+    }
+    // Clear existing prompt
+    runTmux(['send-keys', '-t', options.session, 'Escape'], true);
+    sleepSync(120);
+    runTmux(['send-keys', '-t', options.session, 'C-u'], true);
+    sleepSync(120);
+    // Type the message
+    runTmux(['send-keys', '-t', options.session, '-l', options.message], true);
+    sleepSync(Math.max(120, options.waitMs));
+    // Send Enter(s)
+    const pressEnter = () => runTmux(['send-keys', '-t', options.session, 'C-m'], true);
+    switch (options.entry) {
+        case 'single':
+            pressEnter();
+            break;
+        case 'double':
+            pressEnter();
+            sleepSync(200);
+            pressEnter();
+            break;
+        case 'none':
+            break;
+        default:
+            usage(`Unsupported entry mode: ${options.entry}`);
+    }
+    sleepSync(600);
+    const tail = runTmux(['capture-pane', '-pt', options.session, '-S', '-6'], true);
+    console.log(tail);
+}
+try {
+    const options = parseArgs(process.argv.slice(2));
+    sendMessage(options);
+}
+catch (error) {
+    usage(error instanceof Error ? error.message : String(error));
+}

package/dist/scripts/docs-list.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env tsx
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compact } from 'es-toolkit';
+const docsListFile = fileURLToPath(import.meta.url);
+const docsListDir = dirname(docsListFile);
+const DOCS_DIR = join(docsListDir, '..', 'docs');
+const EXCLUDED_DIRS = new Set(['archive', 'research']);
+function walkMarkdownFiles(dir, base = dir) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (EXCLUDED_DIRS.has(entry.name)) {
+                continue;
+            }
+            files.push(...walkMarkdownFiles(fullPath, base));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(relative(base, fullPath));
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+function extractMetadata(fullPath) {
+    const content = readFileSync(fullPath, 'utf8');
+    if (!content.startsWith('---')) {
+        return { summary: null, readWhen: [], error: 'missing front matter' };
+    }
+    const endIndex = content.indexOf('\n---', 3);
+    if (endIndex === -1) {
+        return { summary: null, readWhen: [], error: 'unterminated front matter' };
+    }
+    const frontMatter = content.slice(3, endIndex).trim();
+    const lines = frontMatter.split('\n');
+    let summaryLine = null;
+    const readWhen = [];
+    let collectingField = null;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line.startsWith('summary:')) {
+            summaryLine = line;
+            collectingField = null;
+            continue;
+        }
+        if (line.startsWith('read_when:')) {
+            collectingField = 'read_when';
+            const inline = line.slice('read_when:'.length).trim();
+            if (inline.startsWith('[') && inline.endsWith(']')) {
+                try {
+                    const parsed = JSON.parse(inline.replace(/'/g, '"'));
+                    if (Array.isArray(parsed)) {
+                        readWhen.push(...compact(parsed.map((item) => String(item).trim())));
+                    }
+                }
+                catch {
+                    // ignore malformed inline arrays
+                }
+            }
+            continue;
+        }
+        if (collectingField === 'read_when') {
+            if (line.startsWith('- ')) {
+                const hint = line.slice(2).trim();
+                if (hint) {
+                    readWhen.push(hint);
+                }
+            }
+            else if (line === '') {
+            }
+            else {
+                collectingField = null;
+            }
+        }
+    }
+    if (!summaryLine) {
+        return { summary: null, readWhen, error: 'summary key missing' };
+    }
+    const summaryValue = summaryLine.slice('summary:'.length).trim();
+    const normalized = summaryValue
+        .replace(/^['"]|['"]$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized) {
+        return { summary: null, readWhen, error: 'summary is empty' };
+    }
+    return { summary: normalized, readWhen };
+}
+console.log('Listing all markdown files in docs folder:');
+const markdownFiles = walkMarkdownFiles(DOCS_DIR);
+for (const relativePath of markdownFiles) {
+    const fullPath = join(DOCS_DIR, relativePath);
+    const { summary, readWhen, error } = extractMetadata(fullPath);
+    if (summary) {
+        console.log(`${relativePath} - ${summary}`);
+        if (readWhen.length > 0) {
+            console.log(`  Read when: ${readWhen.join('; ')}`);
+        }
+    }
+    else {
+        const reason = error ? ` - [${error}]` : '';
+        console.log(`${relativePath}${reason}`);
+    }
+}
+console.log('\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above (React hooks, cache directives, database work, tests, etc.), read that doc before coding, and suggest new coverage when it is missing.');

package/dist/scripts/git-policy.js

@@ -0,0 +1,125 @@
+import { resolve } from 'node:path';
+const COMMIT_HELPER_SUBCOMMANDS = new Set(['add', 'commit']);
+const GUARDED_SUBCOMMANDS = new Set(['push', 'pull', 'merge', 'rebase', 'cherry-pick']);
+const DESTRUCTIVE_SUBCOMMANDS = new Set([
+    'reset',
+    'checkout',
+    'clean',
+    'restore',
+    'switch',
+    'stash',
+    'branch',
+    'filter-branch',
+    'fast-import',
+]);
+export function extractGitInvocation(commandArgs) {
+    for (const [index, token] of commandArgs.entries()) {
+        if (token === 'git' || token.endsWith('/git')) {
+            return { index, argv: commandArgs.slice(index) };
+        }
+    }
+    return null;
+}
+export function findGitSubcommand(commandArgs) {
+    if (commandArgs.length <= 1) {
+        return null;
+    }
+    const optionsWithValue = new Set(['-C', '--git-dir', '--work-tree', '-c']);
+    let index = 1;
+    while (index < commandArgs.length) {
+        const token = commandArgs[index];
+        if (token === undefined) {
+            break;
+        }
+        if (token === '--') {
+            const next = commandArgs[index + 1];
+            return next ? { name: next, index: index + 1 } : null;
+        }
+        if (!token.startsWith('-')) {
+            return { name: token, index };
+        }
+        if (token.includes('=')) {
+            index += 1;
+            continue;
+        }
+        if (optionsWithValue.has(token)) {
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return null;
+}
+export function determineGitWorkdir(baseDir, gitArgs, command) {
+    let workDir = baseDir;
+    const limit = command ? command.index : gitArgs.length;
+    let index = 1;
+    while (index < limit) {
+        const token = gitArgs[index];
+        if (token === undefined) {
+            break;
+        }
+        if (token === '-C') {
+            const next = gitArgs[index + 1];
+            if (next) {
+                workDir = resolve(workDir, next);
+            }
+            index += 2;
+            continue;
+        }
+        if (token.startsWith('-C')) {
+            const pathSegment = token.slice(2);
+            if (pathSegment.length > 0) {
+                workDir = resolve(workDir, pathSegment);
+            }
+        }
+        index += 1;
+    }
+    return workDir;
+}
+export function analyzeGitExecution(commandArgs, workspaceDir) {
+    const invocation = extractGitInvocation(commandArgs);
+    const command = invocation ? findGitSubcommand(invocation.argv) : null;
+    const workDir = invocation ? determineGitWorkdir(workspaceDir, invocation.argv, command) : workspaceDir;
+    return {
+        invocation,
+        command,
+        subcommand: command?.name ?? null,
+        workDir,
+    };
+}
+export function requiresCommitHelper(subcommand) {
+    if (!subcommand) {
+        return false;
+    }
+    return COMMIT_HELPER_SUBCOMMANDS.has(subcommand);
+}
+export function requiresExplicitGitConsent(subcommand) {
+    if (!subcommand) {
+        return false;
+    }
+    return GUARDED_SUBCOMMANDS.has(subcommand);
+}
+export function isDestructiveGitSubcommand(command, gitArgv) {
+    if (!command) {
+        return false;
+    }
+    const subcommand = command.name;
+    if (DESTRUCTIVE_SUBCOMMANDS.has(subcommand)) {
+        return true;
+    }
+    if (subcommand === 'bisect') {
+        const action = gitArgv[command.index + 1] ?? '';
+        return action === 'reset';
+    }
+    return false;
+}
+export function evaluateGitPolicies(context) {
+    const invocationArgv = context.invocation?.argv;
+    const normalizedArgv = Array.isArray(invocationArgv) ? invocationArgv : [];
+    return {
+        requiresCommitHelper: requiresCommitHelper(context.subcommand),
+        requiresExplicitConsent: requiresExplicitGitConsent(context.subcommand),
+        isDestructive: isDestructiveGitSubcommand(context.command, normalizedArgv),
+    };
+}