@unblocklabs/unblock-codex-prompt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unblock Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# Unblock Codex Prompt
+
+A small, explicit prompt-management bridge for dedicated OpenClaw Mac agents.
+**Version 0.1.0.** The frozen bridge is pinned to OpenClaw/Codex plugin 2026.9.2.
+
+## What you control
+
+- Optional `promptUrl`: a shared policy from Fleet Prompt, replacing both bundled
+  policy files below. Agent-specific identity still comes from local documents.
+- `prompts/system.md`: the shared Codex operating contract, with an optional name.
+- `prompts/developer.md`: the reviewed OpenClaw integration policy.
+- Each agent's local snapshot of `SOUL.md`, `IDENTITY.md`, `USER.md`, its eligible
+  model-visible OpenClaw skills catalog, and a memory reference (not memory bodies).
+
+The snapshot replaces Codex's base instructions through `model_instructions_file`.
+With `frozenContext` enabled, a narrowly patched Codex adapter replaces the generic
+OpenClaw developer policy and suppresses only the soul, memory and OpenClaw-skills
+contributions to collaboration instructions. Default-mode and cron guidance remain.
+
+**Still live and untouched:** native AGENTS.md, native skills, tool schemas and
+executor protocol, sandbox/approvals, native collaboration, channel/time/routing
+context and user messages. `extraSystemPrompt` is retained. This is not total
+prompt ownership; other plugins/hooks can still add instructions.
+
+Customer documents stay on each agent's machine, outside this package. Snapshot
+files use private permissions. Missing identity documents are recorded as absent.
+
+## Compatibility
+
+- Frozen bridge: **OpenClaw 2026.9.2 and @openclaw/codex 2026.9.2 only**. The exact
+  original adapter SHA-256 is checked before patching. Unknown builds are refused.
+- Managed local stdio Codex, agent-scoped home, no custom command/arguments.
+- One target agent per installation. Other agents use upstream behavior. Native
+  children may inherit the parent's frozen context.
+
+This bridge uses two private upstream seams because public prompt hooks cannot
+fix the dropped-context path: one skill-catalog builder and two entry points in
+one Codex adapter bundle. It is deliberately version-pinned, not upgrade-proof.
+The catalog uses OpenClaw's eligibility, allowlist, visibility and size-limit
+logic. Session-specific and execution-directory skills are not snapshotted.
+Remote-node-only skills are not added; this is for dedicated local Mac agents.
+
+## Install and enroll
+
+```sh
+npm ci
+npm run preflight
+npm pack
+openclaw plugins install ./unblocklabs-unblock-codex-prompt-0.1.0.tgz --force --accept-capabilities
+```
+
+Include the plugin in `plugins.allow` if applicable, then configure:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "unblock-codex-prompt": {
+        enabled: true,
+        config: {
+          agentId: "main", agentName: "Bill", frozenContext: true,
+          promptUrl: "https://fleet-prompt.unblocklabs.ai/prompt?channel=dev"
+        }
+      }
+    }
+  }
+}
+```
+
+`agentId` defaults to `main`; `agentName` is optional. `frozenContext` defaults to
+false for existing base-prompt-only users. No conversation-access hook grant is
+needed. After initial enrollment, `promptUrl` enables daily shared-prompt refresh
+and overdue startup catch-up. Startup never rebuilds local context or patches the
+adapter. The optional model-catalog service can also refresh metadata.
+
+`promptUrl` requires `frozenContext`. Use `channel=dev` for Bill and `channel=prod`
+for approved fleet deployments. The URL must use HTTPS without embedded credentials
+or a fragment. Sync fetches without authentication, refuses redirects, and checks
+plain-text content, a 256 KiB limit, UTF-8, and the endpoint's SHA-256
+`X-Prompt-Revision` header, with a ten-second request timeout. These integrity
+checks are not a signature; the configured HTTPS publisher controls the policy.
+
+The remote text replaces the bundled Codex contract; a short developer-layer
+pointer replaces OpenClaw's generic developer policy instead of retaining the old
+`prompts/developer.md` policy copy. The frozen local context is still appended.
+No local documents are sent to the Worker. The installed snapshot is the local
+last-known-good copy: a failed fetch aborts sync before writes, never silently
+falls back to a bundled prompt, and does not disrupt normal turns. Status shows
+the installed URL/revision separately from the configured URL, without fetching.
+
+Back up configuration and drain active work. Inspect the installed official
+Codex package location, then use that exact directory:
+
+```sh
+openclaw plugins inspect codex --json
+openclaw codex-prompt sync --adopt --codex-plugin-dir /absolute/path/to/@openclaw/codex
+openclaw codex-prompt status
+```
+
+`--adopt` explicitly takes ownership of an existing custom prompt pointer. Its
+previous value is retained for restoration; leave the original file in place.
+First frozen sync compiles local documents/catalog and installs the guarded
+adapter patch with a private original-source backup. Later syncs reuse its receipt.
+
+## Refresh and activate
+
+```sh
+openclaw codex-prompt sync
+openclaw codex-prompt status
+```
+
+Only explicit `sync` rebuilds local documents, skills, and the adapter policy.
+With `promptUrl`, the daily service fetches the configured Worker channel and
+replaces only the shared prompt prefix when its content changes. The existing
+frozen context is preserved byte-for-byte, without rereading workspace files.
+Editing a source document or restarting does not rebuild that local snapshot.
+Skill bodies remain files the model reads when triggered; their contents are not
+frozen. The catalog and its selection are frozen.
+
+**After sync, drain work, restart the Gateway/managed app-server, and use new
+conversations.** Existing native threads may retain earlier base instructions.
+The plugin never interrupts or resets sessions. Capture an actual request after
+provisioning or upgrades; `status` is disk evidence, not live adoption.
+
+The patched assembly boundary validates enrollment, pointer and compiled prompt
+hash before replacing/suppressing context. Invalid state aborts assembly.
+This guard does not attest to an old thread's retained prompt or detect every
+possible higher-priority Codex config override. An upgrade replacing the adapter
+removes the guard; startup status is diagnostic, not a global inference gate.
+Restore before upgrading, then revalidate compatibility before reenrollment.
+
+### Daily shared-prompt refresh
+
+No additional setting is needed beyond an enrolled `promptUrl`. The service checks
+every 24 hours while the Gateway runs and catches up when overdue on startup.
+Use `openclaw codex-prompt refresh` to run the same remote-prompt and enabled
+model-catalog refresh immediately, without resnapshotting local context.
+
+Both components are attempted independently: a catalog outage cannot prevent a
+prompt update, or vice versa. Failed fetches or validation keep the installed
+copy; failures retry hourly. Unchanged prompt content is not rewritten. Status
+includes the remote revision and last successful `checkedAt` timestamp. Updates
+are intended for fresh conversations; existing conversations are left alone.
+The plugin never restarts the Gateway automatically.
+
+Existing remote snapshots migrate their shared/context boundary without rereading
+agent files. Ambiguous or externally modified snapshots are refused rather than
+guessed; inspect them and use explicit `sync` to rebuild when appropriate.
+
+## Optional daily model-catalog refresh
+
+Set `suppressExplicitDelegationPrompt: true` alongside `frozenContext: true`, then
+run `openclaw codex-prompt sync` (or `openclaw codex-prompt refresh-catalog` for
+catalog-only updates on an already enrolled agent).
+
+The plugin fetches the configured Codex provider's `/models` endpoint using its
+existing `env_key` credential. The credential must be available in the OpenClaw
+process environment; OAuth-only/command-auth providers are not implemented. The
+endpoint must return a full Codex `models` catalog, not only an OpenAI-style
+`data` list. The managed model cache supplies only the client-version query
+parameter, never the catalog contents.
+
+The plugin preserves upstream model fields and sets only
+`model_messages.multi_agent.mode.explicit` to an empty string on each model. It
+writes `unblock-codex-models.json` in the managed Codex home and sets the top-level
+`model_catalog_json` pointer. It refuses to overwrite another owner's pointer.
+Manual edits to this generated catalog are intentionally replaced on refresh.
+
+While the Gateway is running, the service refreshes every 24 hours and catches
+up if overdue on startup. Failures retain the installed catalog and retry hourly;
+there is no fallback to stale cached metadata. Stopping the service cancels its
+timer and waits for an in-flight refresh. Status exposes last/next refresh times
+and verifies the local catalog hash without fetching. A successful catalog-only
+`refresh-catalog` never changes the fleet prompt or local context snapshot. The
+daily service and `refresh` also check the shared prompt when `promptUrl` is set.
+
+Restart the Gateway after first activating the catalog pointer. On the validated
+managed Codex 0.153.4 build, a fresh conversation adopted refreshed catalog
+contents without a Gateway restart. Content-only updates report
+`newSessionRequired: true`, but `restartRequired: false`. Existing conversations
+are not reset, and their adoption is not guaranteed. The plugin never restarts
+the Gateway automatically; revalidate this behavior when upgrading Codex.
+
+## Restore
+
+```sh
+openclaw codex-prompt restore
+openclaw codex-prompt status
+```
+
+Restore recovers exact original adapter bytes, deactivates enrollment and restores
+the previous TOML pointer. It refuses foreign edits and retains backup, receipt
+and generated files. Restart and use fresh conversations to activate it.
+Restore **before** disabling/uninstalling or changing target agents. Disabling
+without restoring leaves the frozen base but re-enables live injections.
+
+## Safety and scope
+
+- No model-provider endpoint, model, credential or permission changes. Explicit
+  sync/daily refresh can download the public prompt; opt-in catalog refresh uses the existing
+  provider authentication path. Credentials are never written into catalog files.
+- Parsed TOML edits preserve unrelated bytes. Regular-file checks, atomic swaps,
+  concurrency checks and a prompt sync lock protect updates. There is no
+  cross-file transaction; inspect a failed sync and rerun after resolving errors.
+- Do not run concurrent sync/install/restore operations. If a crash left an empty
+  lock directory, confirm no sync is running before removing it.
+- A prompt guides behavior; it is not a security boundary or obedience guarantee.
+- Frozen prompts do not inherit upstream base-policy improvements. Review upgrades.
+- Never commit customer snapshots, raw captures, credentials or host backups.
+
+## Development and release
+
+```sh
+npm run preflight
+npm run release:check -- v0.1.0
+```
+
+Tests cover compilation, explicit refresh, native/private-body exclusion,
+target/disabled/restored behavior, cron/default preservation, malformed state,
+pointer ownership and foreign edits. See [VALIDATION.md](VALIDATION.md) for live
+proof and limits.
+
+Install with
+`openclaw plugins install npm:@unblocklabs/unblock-codex-prompt@0.1.0 --accept-capabilities`.
+The existing [GitHub Release workflow](RELEASING.md) publishes npm only when a
+GitHub Release is published. Normal pushes do not release the package.
+
+References: [Codex configuration](https://developers.openai.com/codex/config-reference),
+[OpenClaw Codex hook boundaries](https://docs.openclaw.ai/plugins/codex-harness-runtime/hooks).

package/RELEASING.md

@@ -0,0 +1,72 @@
+# Releasing
+
+Publishing requires explicit owner approval.
+
+This mirrors the `unblock-memory` release-on-release workflow: normal pushes and
+pull requests run CI only. A **published GitHub Release** runs npm publication.
+Do not create a release merely to test the workflow.
+
+## One-time npm setup
+
+The package is `@unblocklabs/unblock-codex-prompt` with public access.
+
+- Verify publishing rights to the `@unblocklabs` scope.
+- For the first publish, configure an appropriately scoped `NPM_TOKEN` repository
+  secret if npm trusted publishing cannot yet be configured for the new package.
+  Do not put a token in source or copy a host's `.npmrc` into the repository.
+- Configure npm's GitHub Actions trusted publisher for organization
+  `unblocklabs-ai`, repository `unblock-codex-prompt`, workflow `release.yml`.
+  The workflow uses Node 24, npm 11.13.0, `id-token: write`, and provenance.
+  Once OIDC is configured, the token can be removed.
+- Without valid publishing credentials/trust, the release job fails; it does not
+  report a successful release while skipping npm.
+
+If first-package bootstrapping is needed, an authenticated owner can publish the
+reviewed version once with `npm publish --access public`, then configure trust:
+
+```sh
+npm trust github @unblocklabs/unblock-codex-prompt --repo unblocklabs-ai/unblock-codex-prompt --file release.yml --yes
+```
+
+The Release workflow verifies the registry's tarball integrity against its own
+packed artifact before accepting an already-published version. Different bytes
+fail the job. Subsequent new versions publish through OIDC with provenance; a
+local bootstrap publication does not have GitHub Actions provenance.
+
+ClawHub publishing is not configured.
+
+## Release checklist
+
+1. Update `package.json`, `package-lock.json` (including its root package), and
+   `openclaw.plugin.json` to the same version.
+2. Review the prompt diff separately from code changes. Render Bill's name and
+   verify a real fresh-session Responses request after meaningful prompt or
+   compatibility changes. Keep captures private; publish only sanitized findings.
+3. Run `npm ci`, `npm run preflight`, and `npm run release:check -- vX.Y.Z`.
+4. Commit and push reviewed changes to `main`; require passing CI.
+5. With explicit release approval, publish a GitHub Release `vX.Y.Z` targeting
+   `main`. Use release notes that explain user-visible changes and activation.
+6. Watch the Release workflow. Verify local/main/tag commit parity and
+   `npm view @unblocklabs/unblock-codex-prompt@X.Y.Z version dist.integrity`.
+7. Update one fleet node, sync, restart safely, and verify before wider rollout.
+
+The workflow checks release-tag ancestry and all three version-bearing files,
+runs preflight, then publishes with `latest` (or `next` for a prerelease).
+
+## Private request-capture protocol
+
+Use a localhost-only Responses receiver and a new capture directory, mode 0700.
+Never capture real user turns intentionally; use dedicated no-delivery sessions.
+Back up the managed Codex TOML privately before temporarily changing the provider
+endpoint. Preserve credentials and unrelated settings, and arrange restoration
+even if the test fails.
+
+Capture template A, make one unmistakable but harmless temporary template change,
+sync, and capture template B in a **different native thread**. Assert the rendered
+base prompt appears exactly once (allowing Codex's outer-whitespace trimming),
+the marker changes, and OpenClaw developer guidance still exists separately.
+Inspect both `instructions` and developer text items in `input`: Bill's current
+Codex build carries the base prompt in `input`, not `instructions`. A synthetic receiver
+proves wire composition, not model obedience. Restore the canonical template and
+real endpoint, verify a real model turn, and check Gateway health. Never commit
+the marker, raw captures, local ports/PIDs, private config, or test conversations.

package/dist/adapter.d.ts

@@ -0,0 +1,37 @@
+type Receipt = {
+    schema: 1;
+    packageDir: string;
+    path: string;
+    originalSha256: string;
+    patchedSha256: string;
+};
+export declare function readReceipt(agentDir: string): Promise<Receipt | null>;
+export declare function patchAdapterSource(source: string, agentDir: string, agentId: string, runtimePath: string): string;
+export declare function prepareAdapter(agentDir: string, agentId: string, suppliedDir?: string): Promise<{
+    path: string;
+    current: string;
+    original: string;
+    patched: string;
+    receipt: {
+        schema: 1;
+        packageDir: string;
+        path: string;
+        originalSha256: string;
+        patchedSha256: string;
+    };
+}>;
+export declare function installAdapter(agentDir: string, plan: Awaited<ReturnType<typeof prepareAdapter>>): Promise<{
+    adapterChanged: boolean;
+    restartRequired: boolean;
+}>;
+export declare function adapterStatus(agentDir: string): Promise<{
+    installed: boolean;
+    path?: never;
+    supportedVersion?: never;
+} | {
+    installed: boolean;
+    path: string;
+    supportedVersion: string;
+}>;
+export declare function restoreAdapter(agentDir: string): Promise<void>;
+export {};

package/dist/adapter.js

@@ -0,0 +1,104 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readOptional, replaceFile, sha256 } from "./manager.js";
+import { SUPPORTED_OPENCLAW, openclawRoot } from "./compiler.js";
+const ORIGINAL_SHA256 = "344d4a6332d59b5eb1d7551d6d308563f339d5d2251809c8f25e8cec04ede342";
+const MARKER = "// unblock-codex-prompt bridge v1";
+const developer = "function buildDeveloperInstructions(params, options = {}) {";
+const collaboration = "function buildTurnScopedCollaborationInstructions(params, options = {}) {";
+function receiptPath(agentDir) { return join(agentDir, "codex-home", ".unblock-codex-prompt-adapter.json"); }
+function backupPath(agentDir) { return join(agentDir, "codex-home", ".unblock-codex-prompt-adapter-original.js"); }
+export async function readReceipt(agentDir) {
+    const source = await readOptional(receiptPath(agentDir));
+    if (source === null)
+        return null;
+    const value = JSON.parse(source);
+    if (!value || typeof value !== "object" || !("schema" in value) || value.schema !== 1 ||
+        !("packageDir" in value) || typeof value.packageDir !== "string" ||
+        !("path" in value) || typeof value.path !== "string" ||
+        !("originalSha256" in value) || value.originalSha256 !== ORIGINAL_SHA256 ||
+        !("patchedSha256" in value) || typeof value.patchedSha256 !== "string" ||
+        value.path !== join(value.packageDir, "dist", "thread-lifecycle-DPK30jad.js"))
+        throw new Error("Invalid adapter receipt");
+    return { schema: 1, packageDir: value.packageDir, path: value.path, originalSha256: value.originalSha256, patchedSha256: value.patchedSha256 };
+}
+export function patchAdapterSource(source, agentDir, agentId, runtimePath) {
+    if (source.includes(MARKER) || source.split(developer).length !== 2 || source.split(collaboration).length !== 2)
+        throw new Error("Unsupported Codex adapter shape");
+    const prefix = `${MARKER}
+import { createRequire as unblockPromptCreateRequire } from "node:module";
+const unblockPromptRequire = unblockPromptCreateRequire(import.meta.url);
+function unblockFrozenPolicy(params) {
+  const plugins = params.config?.plugins;
+  const entry = plugins?.entries?.["unblock-codex-prompt"];
+  if (plugins?.enabled === false || entry?.enabled !== true || entry.config?.frozenContext !== true ||
+      (Array.isArray(plugins.allow) && !plugins.allow.includes("unblock-codex-prompt"))) return null;
+  const target = entry.config?.agentId ?? "main";
+  if (params.agentId !== target) return null;
+  if (target !== ${JSON.stringify(agentId)}) throw new Error("Frozen bridge target changed; restore and reinstall the adapter");
+  return unblockPromptRequire(${JSON.stringify(runtimePath)}).readFrozenPolicy(${JSON.stringify(agentDir)});
+}
+`;
+    return prefix + source.replace(developer, `${developer}
+\tconst unblockPolicy = unblockFrozenPolicy(params);
+\tif (unblockPolicy !== null) return [unblockPolicy, params.extraSystemPrompt].filter(section => typeof section === "string" && section.trim()).join("\\n\\n");`)
+        .replace(collaboration, `${collaboration}
+\tif (unblockFrozenPolicy(params) !== null) return params.trigger === "cron" ? buildCronCollaborationInstructions() : buildDefaultCollaborationInstructions();`);
+}
+export async function prepareAdapter(agentDir, agentId, suppliedDir) {
+    await openclawRoot();
+    const receipt = await readReceipt(agentDir);
+    const packageDir = suppliedDir ? resolve(suppliedDir) : receipt?.packageDir;
+    if (!packageDir)
+        throw new Error("First frozen sync requires --codex-plugin-dir from openclaw plugins inspect codex --json");
+    if (receipt && receipt.packageDir !== packageDir)
+        throw new Error("Restore the previous adapter before changing Codex installations");
+    const pkg = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+    if (!pkg || typeof pkg !== "object" || !("name" in pkg) || pkg.name !== "@openclaw/codex" || !("version" in pkg) || pkg.version !== SUPPORTED_OPENCLAW)
+        throw new Error(`Frozen bridge requires @openclaw/codex ${SUPPORTED_OPENCLAW}`);
+    const files = (await readdir(join(packageDir, "dist"))).filter(name => /^thread-lifecycle-[\w-]+\.js$/u.test(name));
+    if (files.length !== 1 || files[0] !== "thread-lifecycle-DPK30jad.js")
+        throw new Error("Unsupported Codex bundle layout");
+    const path = join(packageDir, "dist", files[0]);
+    const current = await readOptional(path);
+    if (current === null)
+        throw new Error("Missing Codex adapter");
+    const original = receipt ? await readOptional(backupPath(agentDir)) : current;
+    if (original === null || sha256(original) !== ORIGINAL_SHA256)
+        throw new Error("Unknown Codex adapter bytes; refusing to patch");
+    if (receipt && sha256(current) !== receipt.patchedSha256 && current !== original)
+        throw new Error("Codex adapter changed by another writer; refusing to overwrite");
+    const patched = patchAdapterSource(original, agentDir, agentId, fileURLToPath(new URL("./runtime.js", import.meta.url)));
+    return { path, current, original, patched, receipt: { schema: 1, packageDir, path, originalSha256: ORIGINAL_SHA256, patchedSha256: sha256(patched) } };
+}
+export async function installAdapter(agentDir, plan) {
+    const backup = await readOptional(backupPath(agentDir));
+    if (backup !== null && backup !== plan.original)
+        throw new Error("Foreign adapter backup");
+    await replaceFile(backupPath(agentDir), backup, plan.original);
+    // Receipt first allows crash recovery; source swap is atomic and guarded.
+    await replaceFile(receiptPath(agentDir), await readOptional(receiptPath(agentDir)), `${JSON.stringify(plan.receipt, null, 2)}\n`);
+    return { adapterChanged: await replaceFile(plan.path, plan.current, plan.patched), restartRequired: true };
+}
+export async function adapterStatus(agentDir) {
+    const receipt = await readReceipt(agentDir);
+    if (!receipt)
+        return { installed: false };
+    const current = await readOptional(receipt.path);
+    return { installed: current !== null && sha256(current) === receipt.patchedSha256, path: receipt.path, supportedVersion: SUPPORTED_OPENCLAW };
+}
+export async function restoreAdapter(agentDir) {
+    const receipt = await readReceipt(agentDir);
+    if (!receipt)
+        return;
+    const current = await readOptional(receipt.path);
+    const original = await readOptional(backupPath(agentDir));
+    if (original === null || sha256(original) !== receipt.originalSha256)
+        throw new Error("Adapter backup invalid");
+    if (current === original)
+        return;
+    if (current === null || sha256(current) !== receipt.patchedSha256)
+        throw new Error("Foreign adapter edit; refusing restore");
+    await replaceFile(receipt.path, current, original);
+}

package/dist/catalog.d.ts

@@ -0,0 +1,51 @@
+export declare const CATALOG_REFRESH_MS: number;
+export declare function patchCatalog(value: unknown): {
+    models: {
+        model_messages: {
+            multi_agent: {
+                mode: {
+                    explicit: string;
+                };
+            };
+        };
+    }[];
+};
+/** Use the configured provider, not the override file or its refreshable cache. */
+export declare function fetchUpstreamCatalog(agentDir: string, configText: string, request?: typeof fetch): Promise<unknown>;
+export declare function catalogStatus(agentDir: string): Promise<{
+    enabled: boolean;
+    catalogPath: string;
+    pointerMatches: boolean;
+    contentMatches: boolean;
+    refreshedAt: number | null;
+    nextRefreshAt: number | null;
+    modelCount: number;
+}>;
+export declare function refreshCatalog(agentDir: string, options?: {
+    automatic?: boolean;
+    now?: number;
+    fetchCatalog?: typeof fetchUpstreamCatalog;
+}): Promise<{
+    skipped: boolean;
+    changed: boolean;
+    catalogChanged?: never;
+    configChanged?: never;
+    modelCount?: never;
+    refreshedAt?: never;
+    sha256?: never;
+    restartRequired?: never;
+    newSessionRequired?: never;
+} | {
+    changed: boolean;
+    catalogChanged: boolean;
+    configChanged: boolean;
+    modelCount: number;
+    refreshedAt: number;
+    sha256: string;
+    restartRequired: boolean;
+    newSessionRequired: boolean;
+    skipped?: never;
+}>;
+export declare function restoreCatalog(agentDir: string): Promise<void>;
+/** Start promptly if overdue, persist successful refresh time, retry failures hourly. */
+export declare function startCatalogRefresh(run: () => Promise<void>, nextAt: number, onError: () => void): () => Promise<void>;