peaks-loop 4.0.37 → 4.0.39

package/dist/services/context/build-dispatch-system-prompt.js

@@ -93,6 +93,47 @@ export const REPORT_CAP_BLOCK = `## Final report cap (mandatory)
 
 Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any longer detail into the artifact file you already own — the parent can \`Read\` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.
 `;
+/**
+ * Slice 2026-09-10-fact-force-gate-adaptation: stand IN FRONT of an external
+ * `PreToolUse` gate instead of explaining its denial after the fact.
+ *
+ * ECC (a third-party plugin under `~/.claude/plugins/`) registers
+ * `gateguard-fact-force.js` on `Edit|Write|MultiEdit`. It denies the first
+ * edit of a file whose facts the agent has not established, and its four-item
+ * message never says two things the agent needs: that the file must be READ
+ * first, and that the edit was NOT applied. Measured failure mode
+ * (session 2026-09-10-session-528a63): the sub-agent reads the denial as
+ * "the tool is broken" and abandons the edit.
+ *
+ * So the block below leads with the STANDING RULE (read before you edit) and
+ * names the paths it covers, and mentions the denial only as the consequence
+ * of skipping that rule. A sub-agent that has never seen the gate can read
+ * this once and never trip it.
+ *
+ * The gate itself is untouched: peaks-loop adapts to it, and does NOT disable,
+ * bypass, or re-implement it. Nor is `ECC_GATEGUARD=off` part of this.
+ *
+ * Always rendered — no opt-out flag and no role split. Every role edits files
+ * outside `.peaks/**`, and only sub-agent #1 of a session sees a denial (the
+ * gate fires once per file), so a role-scoped or opt-in block would leave the
+ * rest of the fleet untold. It joins the stable boilerplate prefix: constant
+ * bytes for every dispatch, prompt-cache friendly.
+ *
+ * The `.peaks/**` exemption is real and pre-dates this slice — peaks-loop
+ * materialises `.claude/settings.local.json` so the gate skips `.peaks/**`
+ * (slice 2.0.1-bug3-fact-forcing-bypass; see
+ * `src/cli/commands/workspace/init-command.ts`).
+ */
+export const FACT_FORCE_GATE_BLOCK = `## Read before you edit (Fact-Forcing Gate)
+
+Read a file BEFORE your first \`Edit\` / \`Write\` / \`MultiEdit\` on it — the normal way to work here, not an optional step. It applies to every path OUTSIDE \`.peaks/**\` (source, tests, docs, config); \`.peaks/**\` writes are exempt.
+
+Skipping that read trips a \`PreToolUse\` plugin gate (ECC's "Fact-Forcing Gate"), which denies the edit. A denial is NOT a failure and the tool is NOT broken — your edit was NOT applied. Read the file, state the four facts the gate asks for (importers, affected API, data schemas if any, the user's verbatim instruction), then retry the same operation. Do not switch tools, do not give up, do not re-attempt blindly.
+`;
+/** Always-on renderer for {@link FACT_FORCE_GATE_BLOCK}. */
+export function renderFactForceGateBlock() {
+    return `${FACT_FORCE_GATE_BLOCK}\n`;
+}
 /**
  * Compose the system-prompt body for a sub-agent dispatch.
  *
@@ -104,7 +145,7 @@ Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any lon
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
  * controller brief): when the memory block is unavailable, the composed body is
  * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
- * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * "\n" + REPORT_CAP + "\n" + FACT_FORCE_GATE + "\n" + contextBlock + taskBody`, so the unavailable
  * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
  * (REPORT_CAP joined the stable prefix in slice
  * 2026-09-10-context-audit-and-discipline, Slice C.)
@@ -128,15 +169,17 @@ export function buildDispatchSystemPrompt(input) {
     // for every role — the composer owns the injection so callers MUST NOT
     // prepend `formatTestToolDetection()` themselves (double injection).
     const testToolText = `${formatTestToolDetection()}\n\n`;
+    // 2026-09-10-fact-force-gate-adaptation: always-on, both branches.
+    const factForceGateText = renderFactForceGateBlock();
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
     const projectStackText = renderProjectStackBlock(projectStackBlock);
     const freshContextText = renderFreshContextBlock(freshContextBlock);
     const capsuleText = renderCapsulePointer(capsule);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
+    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
 }
 /**
  * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule pointer.
@@ -294,6 +337,15 @@ export const BINDING_RULE_TOKENS = [
     'changed files (one line each)',
     'pass/fail counts',
     'tsc status',
+    // fact-forcing gate (slice 2026-09-10-fact-force-gate-adaptation)
+    '## Read before you edit (Fact-Forcing Gate)',
+    'Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on it',
+    'every path OUTSIDE `.peaks/**`',
+    '`PreToolUse` plugin gate',
+    'A denial is NOT a failure and the tool is NOT broken',
+    'your edit was NOT applied',
+    'retry the same operation',
+    'do not re-attempt blindly',
     // test scope — ONE unified block, byte-identical for EVERY role
     '## Test Tool Detection (mandatory)',
     '`package.json#scripts.test`',

package/dist/services/hooks/auto-compact-hook-install.d.ts

@@ -41,12 +41,22 @@ export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
  * heavy lifting (ratio probe + in-band `claude --compact` spawn)
  * lives in the CLI surface, not inlined into the hook.
  *
+ * `--project .` is LOAD-BEARING, not decoration. `--project` is a
+ * `.requiredOption` on `peaks code auto-compact`, and a hook has no way
+ * to prompt for a missing required option. Without this argument the
+ * hook exited with `error: required option '--project <path>' not
+ * specified` on EVERY matching tool call — a non-blocking failure, so
+ * the hook looked installed while the zero-human-intervention
+ * auto-compact contract never once fired. `.` is promoted to the git
+ * root by `resolveCanonicalProjectRoot`, the same convention the
+ * `post-compact-detect` hook already documents in its own option help.
+ *
  * `npx peaks` is deliberately omitted: the project-local install
  * puts `peaks` on PATH inside the consumer repo (postinstall step),
  * so the unqualified command works in the same shell the runner
  * is using.
  */
-export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks code auto-compact";
+export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks code auto-compact --project .";
 /**
  * Magic comment marker that fences the auto-compatchook block.
  * Both install (writes the marker) and remove (matches on it) use
@@ -68,6 +78,9 @@ export type AutoCompactHookInstallResult = {
 } | {
     readonly action: 'already-installed';
     readonly settingsPath: string;
+} | {
+    readonly action: 'updated';
+    readonly settingsPath: string;
 };
 /**
  * Result envelope for `removeAutoCompactHook`.

package/dist/services/hooks/auto-compact-hook-install.js

@@ -44,12 +44,22 @@ export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
  * heavy lifting (ratio probe + in-band `claude --compact` spawn)
  * lives in the CLI surface, not inlined into the hook.
  *
+ * `--project .` is LOAD-BEARING, not decoration. `--project` is a
+ * `.requiredOption` on `peaks code auto-compact`, and a hook has no way
+ * to prompt for a missing required option. Without this argument the
+ * hook exited with `error: required option '--project <path>' not
+ * specified` on EVERY matching tool call — a non-blocking failure, so
+ * the hook looked installed while the zero-human-intervention
+ * auto-compact contract never once fired. `.` is promoted to the git
+ * root by `resolveCanonicalProjectRoot`, the same convention the
+ * `post-compact-detect` hook already documents in its own option help.
+ *
  * `npx peaks` is deliberately omitted: the project-local install
  * puts `peaks` on PATH inside the consumer repo (postinstall step),
  * so the unqualified command works in the same shell the runner
  * is using.
  */
-export const AUTO_COMPACT_HOOK_COMMAND = 'peaks code auto-compact';
+export const AUTO_COMPACT_HOOK_COMMAND = 'peaks code auto-compact --project .';
 /**
  * Magic comment marker that fences the auto-compatchook block.
  * Both install (writes the marker) and remove (matches on it) use
@@ -102,10 +112,6 @@ export function installAutoCompactHook(input) {
     const settings = readSettings(settingsPath);
     const hooks = settings.hooks ?? {};
     const preToolUse = hooks.PreToolUse ?? [];
-    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
-    if (alreadyInstalled) {
-        return { action: 'already-installed', settingsPath };
-    }
     // The matcher is `Bash|Task`, so on Windows this runs on the same
     // Git-Bash / MSYS2 shell-form path as the other peaks Bash hooks, which
     // force-allocates a console window on every matching tool call. The
@@ -113,18 +119,36 @@ export function installAutoCompactHook(input) {
     // `.claude/settings.local.json`, so a machine-specific `shell` cannot
     // leak into a shared file. `undefined` on POSIX omits the key entirely.
     const shell = resolveHookShell();
+    const desiredHook = {
+        type: 'command',
+        command: AUTO_COMPACT_HOOK_COMMAND,
+        ...(shell !== undefined ? { shell } : {})
+    };
+    const existing = preToolUse.find(isAutoCompactEntry);
+    // "Already installed" must mean installed CORRECTLY.
+    //
+    // Keying only off the matcher is how a corrected command never reaches
+    // an existing install: the entry is present, so the installer returns
+    // early and the stale string stays in the settings file forever. That
+    // is not hypothetical — it is exactly how the missing `--project`
+    // survived on every machine that had already installed the hook, and
+    // re-running the installer could not repair any of them.
+    if (existing !== undefined) {
+        if (existing.hooks?.[0]?.command === AUTO_COMPACT_HOOK_COMMAND) {
+            return { action: 'already-installed', settingsPath };
+        }
+        const migrated = preToolUse.map((entry) => isAutoCompactEntry(entry)
+            ? { ...entry, matcher: AUTO_COMPACT_HOOK_MATCHER, hooks: [desiredHook] }
+            : entry);
+        writeSettings(settingsPath, {
+            ...settings,
+            hooks: { ...hooks, PreToolUse: migrated }
+        });
+        return { action: 'updated', settingsPath };
+    }
     const nextPreToolUse = [
         ...preToolUse,
-        {
-            matcher: AUTO_COMPACT_HOOK_MATCHER,
-            hooks: [
-                {
-                    type: 'command',
-                    command: AUTO_COMPACT_HOOK_COMMAND,
-                    ...(shell !== undefined ? { shell } : {})
-                }
-            ]
-        }
+        { matcher: AUTO_COMPACT_HOOK_MATCHER, hooks: [desiredHook] }
     ];
     writeSettings(settingsPath, {
         ...settings,

package/dist/services/lint/detect-ocr-18.d.ts

@@ -7,4 +7,12 @@ export type Ocr18DetectResult = {
     readonly warnings: readonly string[];
     readonly nextActions: readonly string[];
 };
-export declare function detectOcr18(): Ocr18DetectResult;
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export declare const NPX_PROBE_UNRESOLVED_CODE = "NPX_PROBE_UNRESOLVED";
+/**
+ * `cwd` is where the local npm tree is looked for (defaults to the process
+ * cwd, like `runOcr18`'s own `cwd`); the npx cache roots are the machine's.
+ */
+export declare function detectOcr18(options?: {
+    readonly cwd?: string;
+}): Ocr18DetectResult;

package/dist/services/lint/detect-ocr-18.js

@@ -2,32 +2,136 @@
  * 5-state OCR 1.8.x detect. Mirrors the ECC detect shape.
  */
 import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { resolveNpxInvocation } from './npx-resolver.js';
 import { OCR_18_PACKAGE } from './ocr-multilang-adapter.js';
+import { npmExecCacheRoots } from '../../shared/npm-cache.js';
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export const NPX_PROBE_UNRESOLVED_CODE = 'NPX_PROBE_UNRESOLVED';
+// 2026-09-10: `npx` on Windows is an `npx.cmd` shim, which Node refuses to spawn
+// without `shell: true` — a bare `spawnSync('npx', …)` failed with ENOENT and was
+// then reported as "npx is not on PATH" on machines where `npx --version` exits 0.
+// The shim is bypassed through `resolveNpxInvocation` (same helper as
+// `detect-eslint.ts`), and a launch failure is reported as its OWN reason rather
+// than being collapsed into "absent".
 function probeNpx() {
-    const probe = spawnSync('npx', ['--version'], { encoding: 'utf8' });
-    return probe.status === 0;
+    const { command, args, baseEnv } = resolveNpxInvocation(['--version']);
+    // `windowsHide` on every spawn (repo convention): without it this probe pops
+    // a console window on the user's desktop.
+    const probe = spawnSync(command, args, { encoding: 'utf8', windowsHide: true, env: baseEnv });
+    if (probe.status === 0)
+        return { available: true };
+    const error = probe.error;
+    if (error !== undefined && error !== null) {
+        // `command !== 'npx'` ⇒ the resolver located a real npx CLI entry and it STILL
+        // could not be launched — a different failure from "npx is not on PATH".
+        return command !== 'npx'
+            ? { available: false, reason: 'not-launchable', detail: error.message }
+            : { available: false, reason: 'not-on-path', detail: error.message };
+    }
+    return { available: false, reason: 'probe-failed', detail: `npx --version exited ${probe.status ?? 'null'}` };
 }
-function probeOcr18() {
-    const result = spawnSync('npx', ['--package', OCR_18_PACKAGE, '--', 'ocr', 'version'], { encoding: 'utf8' });
-    return result.status === 0;
+/** The scoped directory and exact version a `name@version` spec names. */
+function splitSpec(spec) {
+    const at = spec.lastIndexOf('@');
+    return { dir: spec.slice(0, at), version: spec.slice(at + 1) };
 }
-export function detectOcr18() {
-    if (!probeNpx()) {
+/** The version the `package.json` at `modulesRoot/<dir>` declares, or `null`. */
+function installedVersion(modulesRoot, dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(modulesRoot, dir, 'package.json'), 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        // Nothing installed under this root is the normal case for most of them.
+        return null;
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        // No exec cache at this location is the normal case on a fresh machine.
+        return [];
+    }
+}
+/**
+ * Every `node_modules` tree npm consults BEFORE it installs `--package <spec>`.
+ *
+ * 2026-09-11: this probe used to run `npx --package <pkg> -- ocr version`, which
+ * INSTALLED the package when it was not already resolvable — a network fetch, a
+ * write into the npm cache, and a console window titled `npm i …` on the user's
+ * desktop for seconds. A probe may look; it may not fetch. Presence is decided
+ * the way npm decides it (`libnpmexec/lib/index.js`, npm 11.9.0, read on this
+ * machine): the LOCAL tree first, matched by `node.pkgid === spec.raw` (name AND
+ * exact version), then the `_npx` cache entry; only a double miss installs.
+ */
+function resolvableModuleRoots(cwd) {
+    const roots = [];
+    // The local tree: npm anchors on the project root above the cwd and Node
+    // resolves modules by walking up, so an ancestor's `node_modules` counts too.
+    let dir = resolve(cwd);
+    for (;;) {
+        roots.push(join(dir, 'node_modules'));
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const cacheRoot of npmExecCacheRoots()) {
+        for (const entry of safeReaddir(cacheRoot)) {
+            roots.push(join(cacheRoot, entry, 'node_modules'));
+        }
+    }
+    return roots;
+}
+/**
+ * Whether the pinned package is already resolvable. LOOKS, never fetches: it
+ * spawns nothing at all, so there is no install and no window to hide. The
+ * version must match the pin exactly — any other version is one npm exec would
+ * install over, which is the write this probe exists to avoid.
+ */
+function probeOcr18(cwd) {
+    const { dir, version } = splitSpec(OCR_18_PACKAGE);
+    return resolvableModuleRoots(cwd).some((modulesRoot) => installedVersion(modulesRoot, dir) === version);
+}
+/**
+ * `cwd` is where the local npm tree is looked for (defaults to the process
+ * cwd, like `runOcr18`'s own `cwd`); the npx cache roots are the machine's.
+ */
+export function detectOcr18(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const probe = probeNpx();
+    if (!probe.available) {
+        if (probe.reason === 'not-launchable') {
+            return {
+                state: 'detection-failed',
+                npxAvailable: false,
+                package: OCR_18_PACKAGE,
+                warnings: [`${NPX_PROBE_UNRESOLVED_CODE}: could not launch npx to probe (${probe.detail}).`],
+                nextActions: ['Ensure Node.js >= 20 with its bundled npm is installed; `npx --version` must succeed.']
+            };
+        }
         return {
             state: 'ocr18-missing',
             npxAvailable: false,
             package: OCR_18_PACKAGE,
-            warnings: ['npx is not on PATH'],
+            warnings: [probe.reason === 'not-on-path' ? 'npx is not on PATH' : probe.detail],
             nextActions: ['Install Node.js ≥ 20 with npm to enable `npx --package`.']
         };
     }
-    if (!probeOcr18()) {
+    if (!probeOcr18(cwd)) {
         return {
             state: 'ocr18-missing',
             npxAvailable: true,
             package: OCR_18_PACKAGE,
             warnings: [`could not resolve ${OCR_18_PACKAGE}`],
-            nextActions: ['Run `npm i @alibaba-group/open-code-review@1.8.9` to install the reviewer.']
+            // 2026-09-11: names the explicit acquisition verb rather than an `npm i`
+            // for a human to hand-type. Acquiring is its own VISIBLE step; this probe
+            // stays read-only and never performs it (see `ocr-18-acquire.ts`).
+            nextActions: ['Run `peaks code-review acquire-ocr-18` to fetch the reviewer.']
         };
     }
     return {

package/dist/services/lint/ocr-18-acquire.d.ts

@@ -0,0 +1,113 @@
+import { type ShellProbeRunner } from '../env/shell-probe.js';
+/**
+ * The network wait, named BEFORE it starts and never skipped silently.
+ *
+ * The size is not quoted as a figure the way `INSTALL_SIZE_WARNING` quotes
+ * chromium's 704 MiB: this package's download size is not measured here, and a
+ * guessed number in a warning is worse than no number. What the user needs to
+ * know before the block is that this touches the network and is one-time.
+ */
+export declare const ACQUIRE_NETWORK_WARNING = "fetching @alibaba-group/open-code-review@1.8.9 from the npm registry (needs network, one time)";
+/** Which shell the acquisition runs through, in preference order. */
+export type AcquireShellKind = 'bash' | 'powershell' | 'direct';
+export interface AcquireShell {
+    readonly kind: AcquireShellKind;
+    /** Absolute path to the shell, or `null` for `direct` (nothing is spawned). */
+    readonly path: string | null;
+    /**
+     * ALWAYS populated: which shell was chosen, and when it is not the first
+     * choice, why. A caller that drops this makes the choice silent again.
+     */
+    readonly note: string;
+}
+export interface AcquireOutcome {
+    readonly ok: boolean;
+    /** `''` on success, else `OCR18_ACQUIRE_BUSY` | `OCR18_ACQUIRE_FAILED` | `OCR18_ACQUIRE_TIMEOUT`. */
+    readonly code: string;
+    readonly message: string;
+    /** Which shell ran it, and whether that was the preferred one. */
+    readonly shell: AcquireShell;
+    readonly durationMs: number;
+    /** `[ACQUIRE_NETWORK_WARNING]` whenever this call actually spawned the installer. */
+    readonly warnings: readonly string[];
+}
+/**
+ * `<homedir>/.peaks/ocr/install.lock` — the OCR acquisition lock.
+ *
+ * MACHINE-GLOBAL, like the web install lock and for the same reason: what it
+ * guards is npm's per-user exec cache (`~/.npm/_npx`, `%LOCALAPPDATA%
+ * \npm-cache\_npx`), which every project and every session of this user
+ * shares. A per-project lock would serialize nothing.
+ */
+export declare function ocrAcquireLockPath(): string;
+/**
+ * Take the OCR acquire lock (O_EXCL create), reclaiming a STALE one — dead
+ * owner, unreadable body, or older than `ACQUIRE_LOCK_STALE_MS`. `false` when
+ * another process holds a live lock.
+ *
+ * Same protocol as `web-install-service.acquireInstallLock`, deliberately
+ * including the R15 detail that **the reclaim is a rename, not an unlink**:
+ * `O_EXCL` serializes the create only if the removal before it cannot be
+ * replayed against a fresh file — `A unlink → A create → B unlink (A's FRESH
+ * lock) → B create` leaves both holders. A file can only be moved once, so
+ * exactly one reclaimer wins and the create that follows decides.
+ *
+ * The two copies are not shared because the web module's lock is bound to its
+ * own artifact root and this change does not reach into it. If a third
+ * acquirer appears, lift the pair into a shared helper with a lock-path
+ * parameter rather than writing a third copy.
+ */
+export declare function acquireOcrLock(): boolean;
+/** Release the OCR acquire lock, but only when this process is its owner. */
+export declare function releaseOcrLock(): void;
+export interface ResolveAcquireShellOptions {
+    /** Override `process.platform` (tests simulate a host without Git Bash). */
+    readonly platform?: NodeJS.Platform;
+    /** Override `process.env` (the `PEAKS_GIT_BASH` pin and `SystemRoot` live here). */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * Test seam for BOTH lookups: it answers the Git Bash default paths inside
+     * `probeShell` and the PowerShell path below, so one injected map can
+     * simulate "Windows with no Git Bash" on a host that has it.
+     */
+    readonly probeFile?: (absPath: string) => boolean | Promise<boolean>;
+    /** Test seam forwarded to `probeShell` for its `where bash` PATH sweep. */
+    readonly runner?: ShellProbeRunner;
+}
+/**
+ * Resolve the shell the acquisition runs through: Git Bash → PowerShell →
+ * no shell. Never throws, and never returns a shell without a `note`.
+ */
+export declare function resolveAcquireShell(options?: ResolveAcquireShellOptions): Promise<AcquireShell>;
+/**
+ * The exact argv of the one-time acquisition. Exported so a unit test can
+ * assert the arguments WITHOUT spawning anything — an install is not a test's
+ * side effect (same rule as `installCommandLine`).
+ *
+ * `--yes` is what makes this non-interactive: without it `npx` stops to ask
+ * "Ok to proceed?" on a machine that has not cached the package, which is the
+ * hang this verb exists to avoid.
+ */
+export declare function acquireCommandArgs(): readonly string[];
+/**
+ * The same argv as ONE shell line, for the bash / PowerShell branches.
+ *
+ * Every token is double-quoted, and that is load-bearing rather than
+ * cosmetic: a bare `@alibaba-group/…` is PowerShell's array syntax. Every
+ * token here is a module constant built from `OCR_18_PACKAGE`, so quoting is
+ * sufficient — no token carries a `"`, `\`, `$` or backtick that the two
+ * shells would escape differently, and none is caller-supplied.
+ */
+export declare function acquireCommandLine(): string;
+export interface AcquireOcr18Options {
+    /** True when the caller prints a JSON envelope to stdout and must not be handed npm's. */
+    readonly asJson?: boolean;
+    /** Pre-resolved shell. Production callers omit it; tests inject one. */
+    readonly shell?: AcquireShell;
+}
+/**
+ * Run the acquisition once, under the lock. Returns an outcome on every path —
+ * a held lock, a non-zero exit, a timeout, a thrown spawn — so no caller ever
+ * sees an exception from here, and never a silent no-op.
+ */
+export declare function acquireOcr18(options?: AcquireOcr18Options): Promise<AcquireOutcome>;