@webpresso/agent-kit 0.21.0

package/dist/esm/ci/act-helper.js

@@ -0,0 +1,106 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+const CI_ACT_SECRET_PROFILES = {
+    none: {
+        id: 'none',
+        description: 'No secrets are injected.',
+        allowedKeys: [],
+        requiredKeys: [],
+        defaultSources: [],
+    },
+    'github-api': {
+        id: 'github-api',
+        description: 'GitHub API token surface.',
+        allowedKeys: ['GITHUB_TOKEN', 'GITHUB_PAT'],
+        requiredKeys: [],
+        defaultSources: [],
+    },
+    'neon-control-plane': {
+        id: 'neon-control-plane',
+        description: 'Neon control-plane secrets.',
+        allowedKeys: ['NEON_API_KEY', 'NEON_PROJECT_ID', 'NEON_PARENT_BRANCH_ID'],
+        requiredKeys: ['NEON_API_KEY', 'NEON_PROJECT_ID', 'NEON_PARENT_BRANCH_ID'],
+        defaultSources: [],
+    },
+};
+const WORKFLOW_PROFILES = {
+    'ci.yml': 'none',
+    'testing-e2e.yml': 'none',
+    'testing-e2e-act.yml': 'none',
+    'cleanup-stale-neon-e2e-branches.yml': 'neon-control-plane',
+};
+export function isCiActSecretProfileId(value) {
+    return value in CI_ACT_SECRET_PROFILES;
+}
+export function getCiActSecretProfile(profileId) {
+    return CI_ACT_SECRET_PROFILES[profileId];
+}
+function resolveJobSecretProfile(jobName) {
+    if (!jobName)
+        return undefined;
+    if (jobName === 'cleanup')
+        return 'neon-control-plane';
+    return undefined;
+}
+export function resolveCiActSecretProfile(options) {
+    if (options.explicitProfileId && isCiActSecretProfileId(options.explicitProfileId)) {
+        return getCiActSecretProfile(options.explicitProfileId);
+    }
+    const workflowName = options.workflowPath ? basename(options.workflowPath) : undefined;
+    const workflowProfile = workflowName ? WORKFLOW_PROFILES[workflowName] : undefined;
+    const jobProfile = resolveJobSecretProfile(options.jobName);
+    return getCiActSecretProfile(jobProfile ?? workflowProfile ?? 'none');
+}
+export function pickAllowedSecrets(secretMap, allowedKeys) {
+    if (allowedKeys.length === 0)
+        return {};
+    return Object.fromEntries(allowedKeys.flatMap((key) => {
+        const value = secretMap[key];
+        return typeof value === 'string' && value.length > 0 ? [[key, value]] : [];
+    }));
+}
+export function listMissingRequiredSecrets(secretMap, requiredKeys) {
+    return requiredKeys.filter((key) => {
+        const value = secretMap[key];
+        return typeof value !== 'string' || value.length === 0;
+    });
+}
+export function normalizeActSecretsWithOptions(secretMaps, options) {
+    const merged = {};
+    for (const map of secretMaps) {
+        for (const [key, value] of Object.entries(map)) {
+            if (value.length > 0)
+                merged[key] = value;
+        }
+    }
+    if (options.mapGithubPatToToken && !merged.GITHUB_TOKEN && merged.GITHUB_PAT) {
+        merged.GITHUB_TOKEN = merged.GITHUB_PAT;
+    }
+    return merged;
+}
+export function renderSecretsFile(secretMap) {
+    return Object.entries(secretMap)
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+        .join('\n');
+}
+export function injectDefaultActArgs(args, platform = process.platform, arch = process.arch) {
+    const hasArchitectureFlag = args.includes('--container-architecture');
+    if (platform === 'darwin' && arch === 'arm64' && !hasArchitectureFlag) {
+        return ['--container-architecture', 'linux/amd64', ...args];
+    }
+    return args;
+}
+export function writeTempSecretsFile(secretMap) {
+    const dir = mkdtempSync(join(tmpdir(), 'wp-ci-act-'));
+    const path = join(dir, 'secrets.env');
+    writeFileSync(path, `${renderSecretsFile(secretMap)}\n`, { encoding: 'utf8', mode: 0o600 });
+    return {
+        path,
+        cleanup() {
+            rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}
+//# sourceMappingURL=act-helper.js.map

package/dist/esm/ci/act-runner.d.ts

@@ -0,0 +1,24 @@
+export type CiActEventName = 'pull_request' | 'push' | 'workflow_dispatch';
+export interface PublicCiActOptions {
+    readonly cwd?: string;
+    readonly workflow?: string;
+    readonly workflowPath?: string;
+    readonly job?: string;
+    readonly eventName?: CiActEventName;
+    readonly eventPath?: string;
+    readonly envProfile?: string;
+    readonly containerArchitecture?: string;
+    readonly platformImage?: string;
+    readonly execute?: boolean;
+}
+export interface PublicCiActCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly actArgs: readonly string[];
+}
+export declare function resolveCiActWorkflowPath(options?: PublicCiActOptions): string;
+export declare function buildPublicCiActArgs(options?: PublicCiActOptions): string[];
+export declare function buildPublicCiActCommand(options?: PublicCiActOptions): PublicCiActCommand;
+export declare function sanitizePublicCiActArgv(command: PublicCiActCommand): PublicCiActCommand;
+export declare function assertNoForbiddenCiActArgs(args: readonly string[]): void;
+//# sourceMappingURL=act-runner.d.ts.map

package/dist/esm/ci/act-runner.js

@@ -0,0 +1,71 @@
+import { resolve } from 'node:path';
+import { buildSecretGateCommand } from '#secret-gate/runner.js';
+const DEFAULT_WORKFLOW = 'ci-e2e';
+const DEFAULT_PLATFORM_IMAGE = 'ghcr.io/catthehacker/ubuntu:full-latest';
+export function resolveCiActWorkflowPath(options = {}) {
+    if (options.workflowPath && options.workflowPath.trim().length > 0)
+        return options.workflowPath;
+    const workflow = (options.workflow ?? DEFAULT_WORKFLOW).trim();
+    if (workflow.includes('/') || workflow.endsWith('.yml') || workflow.endsWith('.yaml'))
+        return workflow;
+    return `.github/workflows/${workflow}.yml`;
+}
+export function buildPublicCiActArgs(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const args = [
+        options.eventName ?? 'pull_request',
+        '-W',
+        resolve(cwd, resolveCiActWorkflowPath(options)),
+        '-P',
+        `ubicloud-standard-2=${options.platformImage ?? DEFAULT_PLATFORM_IMAGE}`,
+        '--rm',
+    ];
+    pushOption(args, '-j', options.job);
+    pushOption(args, '-e', options.eventPath ? resolve(cwd, options.eventPath) : undefined);
+    pushOption(args, '--container-architecture', options.containerArchitecture ?? 'linux/amd64');
+    return args;
+}
+export function buildPublicCiActCommand(options = {}) {
+    const actArgs = buildPublicCiActArgs(options);
+    const wrapped = buildSecretGateCommand({
+        runner: 'with-secrets',
+        envProfile: options.envProfile ?? 'secrets-only',
+        command: 'act',
+        args: actArgs,
+    });
+    return { command: wrapped.command, args: wrapped.args, actArgs };
+}
+export function sanitizePublicCiActArgv(command) {
+    return {
+        command: command.command,
+        args: command.args.map(sanitizeArg),
+        actArgs: command.actArgs.map(sanitizeArg),
+    };
+}
+export function assertNoForbiddenCiActArgs(args) {
+    const forbidden = [
+        '--chef-token',
+        '--secret',
+        '-s',
+        '--secret-file',
+        '--env-file',
+        '--bind',
+        '--volume',
+        '-v',
+        '--container-options',
+    ];
+    const found = args.find((arg) => forbidden.includes(arg) || forbidden.some((flag) => arg.startsWith(`${flag}=`)));
+    if (found)
+        throw new Error(`Unsupported unsafe ci act argument: ${found}`);
+}
+function pushOption(args, flag, value) {
+    if (value === undefined || value === '')
+        return;
+    args.push(flag, String(value));
+}
+function sanitizeArg(value) {
+    if (/wp-ci-act-[^/\\]+[/\\]secrets\.env$/u.test(value))
+        return '[INTERNAL_SECRET_FILE]';
+    return value;
+}
+//# sourceMappingURL=act-runner.js.map

package/dist/esm/cli/auto-update/detect-pm.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Package-manager detection for the auto-update installer.
+ *
+ * Returns the `{manager, command}` tuple that the installer can use to
+ * re-install `@webpresso/agent-kit` globally, OR returns `{abort: <reason>}`
+ * when no safe install command can be inferred (e.g. devDep install, Volta
+ * shim, unknown manager). The caller turns `abort` into a notify-only outcome.
+ *
+ * Detection priority:
+ *   0. Source/git install — argv1 resolves into the canonical source clone
+ *      → `git -C <repo> pull` (works for symlink dev installs).
+ *   1. `process.env.npm_config_user_agent` — most reliable; set by the
+ *      manager whenever the CLI is launched via the manager's run wrapper.
+ *   2. Realpath walk of `argv0` looking for store markers (`.pnpm-store`,
+ *      `.bun/install`, `.volta/tools`, `.yarn/global`, Homebrew prefix).
+ *   3. Confirm the install is global; abort if it's a devDep consumer.
+ *   4. Volta / asdf shim → abort with a manual-command hint.
+ *   5. Unknown → abort.
+ */
+export type ManagerName = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'vp' | 'git';
+export interface DetectSuccess {
+    manager: ManagerName;
+    command: string[];
+}
+export interface DetectAbort {
+    abort: string;
+}
+export type DetectResult = DetectSuccess | DetectAbort;
+export declare const PUBLIC_PACKAGE_NAME = "@webpresso/agent-kit";
+export declare const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org";
+/**
+ * Detect whether argv1 is a symlink pointing into a supported source clone.
+ * Returns the git worktree root if so, null otherwise.
+ * Exported for testability.
+ */
+export declare function detectGitInstall(argv1: string): string | null;
+/**
+ * Detect the package manager that owns the running `wp` / agent-kit binary.
+ * Pure function modulo `realpathSync` and `execFileSync` — call sites mock
+ * those for tests.
+ */
+export declare function detect(env: NodeJS.ProcessEnv, argv0: string): DetectResult;
+/**
+ * Parse the `npm_config_user_agent` string. Format examples:
+ *   npm/10.2.4 node/v22.0.0 darwin x64 workspaces/false
+ *   pnpm/10.33.0 npm/? node/v22.0.0 darwin arm64
+ *   yarn/1.22.22 npm/? node/v22.0.0 darwin arm64
+ *   bun/1.1.0 npm/? node/v22.0.0 darwin arm64
+ *
+ * Returns the manager name if the leading token matches a known manager.
+ * Exported for testability.
+ */
+export declare function parseUserAgent(userAgent: string): Exclude<ManagerName, 'git'> | null;
+/**
+ * Look for known package-manager store markers in a realpath. The walk is a
+ * substring check against path segments to avoid false positives in user
+ * directory names.
+ * Exported for testability.
+ */
+export declare function matchStoreMarker(realpath: string): Exclude<ManagerName, 'git'> | null;
+/**
+ * Detect Volta / asdf shim layouts. These intercept the binary lookup such
+ * that an in-place `vp install -g` won't pick up. Returns a user-facing
+ * abort reason or null.
+ * Exported for testability.
+ */
+export declare function detectShim(realpath: string): string | null;
+/**
+ * Cheap confirmation that the binary lives outside of a project-local
+ * `node_modules/.bin` (devDep consumer). The `is-installed-globally` npm
+ * package is the upstream choice; we inline an equivalent check so this
+ * module can be tested without that dep installed.
+ * Exported for testability.
+ */
+export declare function confirmInstalledGlobally(realpath: string, env: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=detect-pm.d.ts.map

package/dist/esm/cli/auto-update/detect-pm.js

@@ -0,0 +1,237 @@
+/**
+ * Package-manager detection for the auto-update installer.
+ *
+ * Returns the `{manager, command}` tuple that the installer can use to
+ * re-install `@webpresso/agent-kit` globally, OR returns `{abort: <reason>}`
+ * when no safe install command can be inferred (e.g. devDep install, Volta
+ * shim, unknown manager). The caller turns `abort` into a notify-only outcome.
+ *
+ * Detection priority:
+ *   0. Source/git install — argv1 resolves into the canonical source clone
+ *      → `git -C <repo> pull` (works for symlink dev installs).
+ *   1. `process.env.npm_config_user_agent` — most reliable; set by the
+ *      manager whenever the CLI is launched via the manager's run wrapper.
+ *   2. Realpath walk of `argv0` looking for store markers (`.pnpm-store`,
+ *      `.bun/install`, `.volta/tools`, `.yarn/global`, Homebrew prefix).
+ *   3. Confirm the install is global; abort if it's a devDep consumer.
+ *   4. Volta / asdf shim → abort with a manual-command hint.
+ *   5. Unknown → abort.
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { delimiter, dirname, sep } from 'node:path';
+export const PUBLIC_PACKAGE_NAME = '@webpresso/agent-kit';
+export const PUBLIC_NPM_REGISTRY = 'https://registry.npmjs.org';
+const VP_INSTALL_COMMAND = [
+    'vp',
+    'install',
+    '-g',
+    PUBLIC_PACKAGE_NAME,
+    '--',
+    '--registry',
+    PUBLIC_NPM_REGISTRY,
+];
+const INSTALL_COMMANDS = {
+    npm: VP_INSTALL_COMMAND,
+    pnpm: VP_INSTALL_COMMAND,
+    yarn: VP_INSTALL_COMMAND,
+    bun: VP_INSTALL_COMMAND,
+    vp: VP_INSTALL_COMMAND,
+};
+/**
+ * Detect whether argv1 is a symlink pointing into a supported source clone.
+ * Returns the git worktree root if so, null otherwise.
+ * Exported for testability.
+ */
+export function detectGitInstall(argv1) {
+    const real = safeRealpath(argv1);
+    if (real === null)
+        return null;
+    try {
+        const topLevel = execFileSync('git', ['-C', dirname(real), 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const remote = execFileSync('git', ['-C', topLevel, 'remote', 'get-url', 'origin'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (remote.includes('webpresso/agent-kit') || remote.includes('webpresso/webpresso')) {
+            return topLevel;
+        }
+    }
+    catch {
+        // not inside a git repo or not the right repo
+    }
+    return null;
+}
+/**
+ * Detect the package manager that owns the running `wp` / agent-kit binary.
+ * Pure function modulo `realpathSync` and `execFileSync` — call sites mock
+ * those for tests.
+ */
+export function detect(env, argv0) {
+    // Priority 0 — source/git install (symlink → repo clone).
+    const gitDir = detectGitInstall(argv0);
+    if (gitDir !== null) {
+        return { manager: 'git', command: ['git', '-C', gitDir, 'pull'] };
+    }
+    // Priority 1 — user-agent string set by the package manager.
+    const userAgent = env.npm_config_user_agent;
+    if (userAgent !== undefined && userAgent !== '') {
+        const fromUa = parseUserAgent(userAgent);
+        if (fromUa !== null) {
+            return { manager: fromUa, command: INSTALL_COMMANDS[fromUa] };
+        }
+    }
+    // Priority 2 — realpath walk of argv0 for store markers.
+    const realpath = safeRealpath(argv0);
+    if (realpath !== null) {
+        // Priority 4 (run before 2 success) — Volta / asdf shims.
+        const shim = detectShim(realpath);
+        if (shim !== null) {
+            return { abort: shim };
+        }
+        const fromPath = matchStoreMarker(realpath);
+        if (fromPath !== null) {
+            if (!confirmInstalledGlobally(realpath, env)) {
+                return {
+                    abort: `${PUBLIC_PACKAGE_NAME} is not a global install (path ${realpath}); auto-install disabled.`,
+                };
+            }
+            return { manager: fromPath, command: INSTALL_COMMANDS[fromPath] };
+        }
+    }
+    // Priority 5 — give up; the caller falls back to notify-only.
+    return {
+        abort: `Unable to detect a package manager for ${PUBLIC_PACKAGE_NAME}; auto-install disabled.`,
+    };
+}
+/**
+ * Parse the `npm_config_user_agent` string. Format examples:
+ *   npm/10.2.4 node/v22.0.0 darwin x64 workspaces/false
+ *   pnpm/10.33.0 npm/? node/v22.0.0 darwin arm64
+ *   yarn/1.22.22 npm/? node/v22.0.0 darwin arm64
+ *   bun/1.1.0 npm/? node/v22.0.0 darwin arm64
+ *
+ * Returns the manager name if the leading token matches a known manager.
+ * Exported for testability.
+ */
+export function parseUserAgent(userAgent) {
+    const trimmed = userAgent.trim();
+    if (trimmed.length === 0)
+        return null;
+    const head = trimmed.split(/\s+/, 1)[0];
+    if (head === undefined)
+        return null;
+    const slash = head.indexOf('/');
+    const name = (slash === -1 ? head : head.slice(0, slash)).toLowerCase();
+    if (name === 'npm' || name === 'pnpm' || name === 'yarn' || name === 'bun' || name === 'vp') {
+        return name;
+    }
+    return null;
+}
+/**
+ * Look for known package-manager store markers in a realpath. The walk is a
+ * substring check against path segments to avoid false positives in user
+ * directory names.
+ * Exported for testability.
+ */
+export function matchStoreMarker(realpath) {
+    const segments = splitPathSegments(realpath);
+    // Vite+ global package store: `~/.vite-plus/packages/...`.
+    if (segments.includes('.vite-plus'))
+        return 'vp';
+    // pnpm: any path under `<store>/.pnpm/...` or containing `.pnpm-store`.
+    if (segments.some((seg) => seg === '.pnpm' || seg === '.pnpm-store' || seg === 'pnpm-global')) {
+        return 'pnpm';
+    }
+    // bun: installs under `~/.bun/install/global/...`.
+    if (segments.includes('.bun') && (segments.includes('install') || segments.includes('global'))) {
+        return 'bun';
+    }
+    // yarn classic global dir is `~/.yarn/global/`.
+    // yarn 2+ uses `.yarn/berry` or `.yarn/cache` for installs.
+    if (segments.includes('.yarn') && (segments.includes('global') || segments.includes('berry'))) {
+        return 'yarn';
+    }
+    // Homebrew (`/usr/local/Cellar/node/...`, `/opt/homebrew/Cellar/...`) and
+    // npm prefix (`/usr/local/lib/node_modules`, `~/.npm-global`) → npm.
+    if (segments.includes('Cellar'))
+        return 'npm';
+    if (segments.includes('node_modules') && segments.includes('lib'))
+        return 'npm';
+    if (segments.includes('.npm-global'))
+        return 'npm';
+    if (segments.includes('.npm') && segments.includes('node_modules'))
+        return 'npm';
+    return null;
+}
+/**
+ * Detect Volta / asdf shim layouts. These intercept the binary lookup such
+ * that an in-place `vp install -g` won't pick up. Returns a user-facing
+ * abort reason or null.
+ * Exported for testability.
+ */
+export function detectShim(realpath) {
+    const segments = splitPathSegments(realpath);
+    if (segments.includes('.volta')) {
+        return `${PUBLIC_PACKAGE_NAME} is managed by Volta; run \`volta install ${PUBLIC_PACKAGE_NAME}\` to upgrade.`;
+    }
+    if (segments.includes('.asdf')) {
+        return `${PUBLIC_PACKAGE_NAME} is managed by asdf; reinstall ${PUBLIC_PACKAGE_NAME} after upgrading the runtime, then run \`asdf reshim nodejs\`.`;
+    }
+    return null;
+}
+/**
+ * Cheap confirmation that the binary lives outside of a project-local
+ * `node_modules/.bin` (devDep consumer). The `is-installed-globally` npm
+ * package is the upstream choice; we inline an equivalent check so this
+ * module can be tested without that dep installed.
+ * Exported for testability.
+ */
+export function confirmInstalledGlobally(realpath, env) {
+    const segments = splitPathSegments(realpath);
+    // If the realpath sits inside a project's node_modules and does NOT match
+    // a known global prefix (`.pnpm-store`, `.bun/install/global`, `.yarn/global`,
+    // `.vite-plus`, `Cellar`, `lib/node_modules`), call it a devDep install.
+    const insideNodeModules = segments.includes('node_modules');
+    if (!insideNodeModules)
+        return true;
+    // Global prefixes contain node_modules but are still global.
+    if (segments.includes('.vite-plus'))
+        return true;
+    if (segments.includes('Cellar'))
+        return true;
+    if (segments.includes('lib') && segments.includes('node_modules'))
+        return true;
+    if (segments.includes('.npm-global'))
+        return true;
+    if (segments.includes('.pnpm') || segments.includes('.pnpm-store'))
+        return true;
+    if (segments.includes('.bun'))
+        return true;
+    if (segments.includes('.yarn') && segments.includes('global'))
+        return true;
+    // Compare against env-provided prefixes when available.
+    const prefix = env.npm_config_prefix ?? env.PNPM_HOME ?? env.BUN_INSTALL;
+    if (prefix !== undefined && prefix !== '' && realpath.startsWith(prefix))
+        return true;
+    return false;
+}
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function splitPathSegments(p) {
+    // Strip drive letter / leading separator, split on the OS separator, drop
+    // empties. Works for both POSIX (`/`) and Windows (`\\`) layouts.
+    const normalized = p.replace(/\\/g, sep);
+    const stripped = normalized.startsWith(sep) ? normalized.slice(sep.length) : normalized;
+    return stripped.split(sep).filter((s) => s.length > 0 && s !== delimiter);
+}
+//# sourceMappingURL=detect-pm.js.map

package/dist/esm/cli/auto-update/installer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deferred install scheduler.
+ *
+ * The auto-update flow calls this synchronously after detecting an
+ * available release. We DON'T wait for the install to finish — the parent
+ * process exits cleanly and the install completes in a detached child.
+ * The next invocation of `webpresso` picks up the new binary.
+ *
+ * Invariants (per plan Architecture decision 3 and Implementation surface
+ * "Auto-update wiring"):
+ *
+ *   - Synchronous: returns before the install starts.
+ *   - Detached + unref: the install survives the parent exit.
+ *   - Tombstone before spawn: `autoInstallInProgress = <pid+ts>` is written
+ *     to the configstore at `<state-root>/update-notifier-cache.json`
+ *     *before* the spawn fires, so concurrent invocations within the
+ *     lockout window (60s) skip the spawn.
+ *   - Stdio captured to file: child stdout / stderr are piped to
+ *     `<state-root>/auto-update.log` via an `openSync` file descriptor —
+ *     not via Node IPC, which would tie child lifetime to parent.
+ *   - Best-effort: any failure inside this function is logged via
+ *     `logUpdateError` and swallowed; the user never sees an exception
+ *     from a successful CLI run.
+ */
+/**
+ * Concurrency-lockout window: a tombstone younger than this is considered
+ * active; further `scheduleDeferredInstall` calls become no-ops.
+ */
+export declare const LOCKOUT_MS = 60000;
+export interface InstallPlan {
+    command: string[];
+}
+export interface Tombstone {
+    autoInstallInProgress: {
+        pid: number;
+        ts: number;
+    };
+}
+export interface ScheduleResult {
+    /** Did we actually fork the install child? */
+    spawned: boolean;
+    /** When falsy, the human-facing reason for skipping. */
+    reason?: string;
+}
+/**
+ * Schedule a deferred install for the supplied command. Synchronous —
+ * spawn() returns immediately; the child runs in the background. The parent
+ * is free to `process.exit(0)` after this call returns.
+ */
+export declare function scheduleDeferredInstall(plan: InstallPlan): ScheduleResult;
+/**
+ * Clear the install-in-progress tombstone. Called by the install wrapper
+ * on exit, or by tests. Best-effort.
+ */
+export declare function clearInstallTombstone(): void;
+/**
+ * Whether the given tombstone is within the lockout window relative to `now`.
+ * Exported for testability.
+ */
+export declare function isTombstoneFresh(tombstone: Tombstone, now: number): boolean;
+/**
+ * Build the canonical tombstone shape. Exported for testability.
+ */
+export declare function buildTombstone(pid: number, ts: number): Tombstone;
+//# sourceMappingURL=installer.d.ts.map