@awak-app/simy-cli 0.5.5 → 0.5.7

package/README.md

@@ -9,14 +9,24 @@ npm install -g @awak-app/simy-cli
 simy --daemon
 ```
 
-When an interactive `simy --daemon` starts and the managed SIMY workflows are
-missing or outdated, the CLI asks once before installing the Codex plugin
+When an interactive `simy --daemon` starts without managed SIMY workflows,
+the CLI asks once before installing the Codex plugin
 marketplace, Codex/Claude SQM skills, and PR hooks. Existing unrelated plugins
 and hooks are preserved. Use `--install-workflows` for explicit non-interactive
 installation or `--no-workflow-prompt` to start the daemon without asking.
-After installation, restart Codex and install SIMY from **Plugins → Personal**
+After installation, restart Codex and find and install **SIMY** in **Plugins**
 before using `@simy` in a new task.
 
+After that first installation, the daemon checks installed workflows at startup
+and every hour, including after a CLI automatic upgrade. It updates only existing
+platform installations and refreshes an already enabled SIMY Codex plugin through
+`codex plugin add`. Plugin versions include a content digest so changed bundles
+receive a fresh cache. Use a new Codex task to pick up updated skills; running
+tasks are not restarted. Missing or disabled plugins are not enabled automatically.
+Failed refreshes retry on the next check without blocking daemon startup.
+`--no-auto-update` or `SIMY_AUTO_UPDATE=0` disables these background updates too;
+`--no-workflow-prompt` only suppresses the initial installation prompt.
+
 This is the recommended installation because the CLI can safely install patch
 and minor releases, and the daemon restarts only when no Agentic Loop task is active. To run
 the interactive chat after installation, use `simy`.
@@ -370,3 +380,14 @@ Publishing is handled by GitHub Actions in `.github/workflows/publish.yml`.
   `@awak-app/simy-cli`.
 - The package check inspects the final npm tarball contents and fails if any
   source map file would be published.
+
+### Repository system scopes
+
+Version 0.5.7 supports signed `system_scope` snapshots from Quality Monitor.
+Each check pins the repository's connected component and graph revision. A new
+check revalidates scoped bundles online; a stale or unavailable scope cannot fall
+back to an older cached component. Minimum and full check proofs retain the
+original snapshot. A scope revision change requires a fresh minimum check.
+Deploy this CLI and the web capability proxy before enabling the backend scope
+requirement. Older clients receive an explicit upgrade error, never an expanded
+organization-wide bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
     "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./src/local-task.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/pre-guardrail-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js && npm run check:sqm",
-    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/reliability.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/workflow-onboarding.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
+    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/reliability.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/workflow-onboarding.js && node --check ./src/sqm/workflow-update.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
     "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.5.5";
+export const CLI_VERSION = "0.5.7";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/index.js

@@ -20,6 +20,7 @@ import {
   installAgentShutdownSignalHandlers,
 } from "./shutdown.js";
 import { prepareDaemonWorkflows } from "./sqm/workflow-onboarding.js";
+import { startWorkflowUpdates } from "./sqm/workflow-update.js";
 import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
 const argv = process.argv.slice(2);
@@ -160,9 +161,15 @@ async function runLocalAgent() {
     quiet: interactive,
     updateManager,
   });
-  const shutdownAgent = createAgentShutdown(agent);
+  let stopWorkflowUpdates = async () => {};
+  const closeAgent = createAgentShutdown(agent);
+  const shutdownAgent = async () => {
+    await stopWorkflowUpdates();
+    await closeAgent();
+  };
   installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
   await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
+  stopWorkflowUpdates = startWorkflowUpdates({ enabled: daemon && !updatesDisabled });
   updateManager.start({
     registry: agent.registry,
     restartDaemon: async (targetVersion) => {

package/src/sqm/agent-skill.js

@@ -117,7 +117,8 @@ export async function installSqmAgentSkill({ home = homedir(), platforms = Objec
 }
 
 export async function inspectCodexPlugin({ home = homedir() } = {}) {
-  const expectedDigest = await directoryDigest(BUNDLED_CODEX_PLUGIN_ROOT);
+  const manifest = await bundledPluginManifest();
+  const expectedDigest = await directoryDigest(BUNDLED_CODEX_PLUGIN_ROOT, { manifest });
   const target = codexPluginPath(home);
   const installedDigest = await directoryDigest(target, { missing: null });
   const marketplacePath = codexMarketplacePath(home);
@@ -125,11 +126,12 @@ export async function inspectCodexPlugin({ home = homedir() } = {}) {
   const entry = Array.isArray(marketplace?.plugins)
     ? marketplace.plugins.find((candidate) => candidate?.name === SIMY_CODEX_PLUGIN_ID)
     : null;
-  const marketplaceMatches = isManagedMarketplaceEntry(entry);
+  const marketplaceMatches = isManagedMarketplaceEntry(entry) &&
+    !hasLegacyMarketplaceDisplayName(marketplace);
   const filesMatch = installedDigest === expectedDigest;
   return {
     plugin_id: SIMY_CODEX_PLUGIN_ID,
-    version: SIMY_CODEX_PLUGIN_VERSION,
+    version: manifest.version,
     path: target,
     marketplace_path: marketplacePath,
     digest: `sha256:${expectedDigest}`,
@@ -163,6 +165,8 @@ async function installCodexPlugin({ home }) {
   await rm(staged, { recursive: true, force: true });
   await rm(backup, { recursive: true, force: true });
   await cp(BUNDLED_CODEX_PLUGIN_ROOT, staged, { recursive: true, errorOnExist: true });
+  await writeFile(path.join(staged, ".codex-plugin", "plugin.json"),
+    `${JSON.stringify(await bundledPluginManifest(), null, 2)}\n`);
   let backedUp = false;
   try {
     if (await pathExists(target)) {
@@ -183,10 +187,11 @@ async function installCodexPlugin({ home }) {
       ? marketplace.name
       : "personal",
     interface: {
-      displayName: "Personal",
+      displayName: "Plugins",
       ...(marketplace.interface && typeof marketplace.interface === "object"
         ? marketplace.interface
         : {}),
+      ...(hasLegacyMarketplaceDisplayName(marketplace) ? { displayName: "Plugins" } : {}),
     },
     plugins: [
       ...plugins.filter((entry) => entry?.name !== SIMY_CODEX_PLUGIN_ID),
@@ -196,6 +201,11 @@ async function installCodexPlugin({ home }) {
   await atomicText(marketplacePath, `${JSON.stringify(nextMarketplace, null, 2)}\n`, 0o600);
 }
 
+function hasLegacyMarketplaceDisplayName(marketplace) {
+  // Keep the marketplace identity stable so existing simy@personal installs work.
+  return marketplace?.name === "personal" && marketplace?.interface?.displayName === "Personal";
+}
+
 function managedMarketplaceEntry() {
   return {
     name: SIMY_CODEX_PLUGIN_ID,
@@ -307,7 +317,14 @@ async function fileDigest(target) {
   }
 }
 
-async function directoryDigest(root, { missing = "throw" } = {}) {
+async function bundledPluginManifest() {
+  const manifest = JSON.parse(await readFile(path.join(BUNDLED_CODEX_PLUGIN_ROOT, ".codex-plugin", "plugin.json"), "utf8"));
+  // A stable content-derived version refreshes Codex's cache only when the bundle changes.
+  const digest = await directoryDigest(BUNDLED_CODEX_PLUGIN_ROOT);
+  return { ...manifest, version: `${manifest.version.split("+")[0]}+codex.${digest}` };
+}
+
+async function directoryDigest(root, { missing = "throw", manifest } = {}) {
   let rootStat;
   try {
     rootStat = await lstat(root);
@@ -331,7 +348,10 @@ async function directoryDigest(root, { missing = "throw" } = {}) {
         continue;
       }
       if (!entry.isFile()) throw new Error(`${target} must be a regular file.`);
-      hash.update(relative).update("\0").update(await readFile(target)).update("\0");
+      const content = manifest && relative === ".codex-plugin/plugin.json"
+        ? `${JSON.stringify(manifest, null, 2)}\n`
+        : await readFile(target);
+      hash.update(relative).update("\0").update(content).update("\0");
     }
   };
   await visit(root);

package/src/sqm/bundle-store.js

@@ -41,13 +41,13 @@ export async function loadKnowledgeBundle({
   }
   const cacheIdentity = normalizedCacheIdentity({ endpoint, accountId, organizationId, repository });
   const location = cacheLocation(cacheRoot, cacheIdentity);
-  const validation = { cliVersion, publicKeys, organizationId };
+  const validation = { cliVersion, publicKeys, organizationId, repository };
   const cached = await readVerifiedCache(location, validation, cacheIdentity);
   const fresh =
     cached &&
     now - cached.fetchedAt < ttlMs &&
     Date.parse(cached.bundle.expires_at) > now;
-  if (!offline && endpoint && (!fresh || refresh)) {
+  if (!offline && endpoint && (!fresh || refresh || cached?.bundle.system_scope)) {
     try {
       const fetched = await fetchBundle({ endpoint, repository, cliVersion, token, organizationId, etag: cached?.etag, fetchImpl });
       if (fetched.notModified) {
@@ -56,6 +56,7 @@ export async function loadKnowledgeBundle({
         await writeMetadata(location, { ...cached.metadata, fetched_at: new Date(now).toISOString(), etag: fetched.etag || cached.etag });
         return result(cached.bundle, [], "cache_revalidated");
       }
+      if (cached?.bundle.system_scope && !fetched.bundle?.system_scope) throw nonFallbackError("SQM Cloud attempted to remove the pinned system scope contract.");
       const discoveredTrust = signingTrustForFetch({
         bundle: fetched.bundle,
         endpoint,
@@ -81,11 +82,12 @@ export async function loadKnowledgeBundle({
       return result(bundle, [], "cloud");
     } catch (error) {
       if (error?.code === "incompatible_cli") throw error;
-      if (error?.fallbackAllowed !== false && cached && Date.parse(cached.bundle.expires_at) > now) return result(cached.bundle, [`SQM Cloud unavailable; using last verified bundle: ${message(error)}`], "stale_cache");
+      if (error?.fallbackAllowed !== false && cached && !cached.bundle.system_scope && Date.parse(cached.bundle.expires_at) > now) return result(cached.bundle, [`SQM Cloud unavailable; using last verified bundle: ${message(error)}`], "stale_cache");
       return result(null, [`SQM knowledge could not be used; shadow checks were skipped: ${message(error)}`], "unavailable");
     }
   }
   if (cached) {
+    if (cached.bundle.system_scope) return result(null, ["SQM system scope must be revalidated online before a new check."], "unavailable");
     if (Date.parse(cached.bundle.expires_at) <= now) return result(null, ["The cached SQM knowledge bundle is expired; shadow checks were skipped."], "unavailable");
     const warnings = [];
     if (offline) warnings.push("SQM is offline; using the last verified knowledge bundle.");
@@ -96,10 +98,12 @@ export async function loadKnowledgeBundle({
   return result(null, [`SQM has no verified cache (${reason}); shadow checks were skipped.`], "unavailable");
 }
 
-export function verifyAndValidate(bundle, { cliVersion, publicKeys, organizationId } = {}) {
+export function verifyAndValidate(bundle, { cliVersion, publicKeys, organizationId, repository } = {}) {
   try { validateKnowledgeBundle(bundle, { cliVersion }); } catch (error) { throw nonFallbackError(message(error), error); }
   if (organizationId && bundle.organization_id !== organizationId) throw nonFallbackError(`SQM bundle organization mismatch: expected ${organizationId}.`);
+  if (bundle.system_scope && repository && bundle.system_scope.repository !== repository.toLowerCase()) throw nonFallbackError("SQM bundle repository system scope does not match this repository.");
   for (const module of bundle.modules) {
+    if (bundle.system_scope && module.scope.visibility === "organization" && !module.scope.repositories.some((repo) => bundle.system_scope.repositories.includes(repo.toLowerCase()))) throw nonFallbackError(`SQM module ${module.id} is outside the repository system.`);
     if (module.scope.visibility === "organization" && module.scope.organization_id !== bundle.organization_id) throw nonFallbackError(`SQM module ${module.id} is scoped to a different organization.`);
   }
   const keyId = bundle.integrity.key_id;
@@ -166,6 +170,7 @@ async function fetchBundle({ endpoint, repository, cliVersion, token, organizati
   const url = new URL(endpoint);
   url.searchParams.set("repository", repository);
   url.searchParams.set("cli_version", cliVersion);
+  url.searchParams.set("scope_version", "1");
   const headers = { Accept: "application/json" };
   if (token) headers.Authorization = `Bearer ${token}`;
   if (organizationId) headers["x-simy-org-id"] = organizationId;

package/src/sqm/index.js

@@ -132,7 +132,7 @@ function toLegacyCheck(minCheck, loaded) {
 }
 
 function bundleIdentity(bundle) {
-  return { id: bundle.bundle_id, version: bundle.version, digest: bundle.integrity.digest, signing_key_id: bundle.integrity.key_id };
+  return { id: bundle.bundle_id, version: bundle.version, digest: bundle.integrity.digest, signing_key_id: bundle.integrity.key_id, ...(bundle.system_scope ? { system_scope: bundle.system_scope } : {}) };
 }
 
 function unavailable(warning, repository = null) {

package/src/sqm/proof.js

@@ -57,6 +57,7 @@ export function buildProof({ organizationId, repository, bundle, minCheck, evalu
       version: bundle.version,
       digest: bundle.integrity.digest,
       signing_key_id: bundle.integrity.key_id,
+      ...(bundle.system_scope ? { system_scope: bundle.system_scope } : {}),
     },
     min_check: {
       result_digest: minCheck.result_digest,

package/src/sqm/validation.js

@@ -17,13 +17,27 @@ const SCENARIO_REQUIREMENTS = new Set(["local", "requires_human", "requires_post
 export function validateKnowledgeBundle(bundle, { cliVersion }) {
   const errors = [];
   object(bundle, "$", errors);
-  exactKeys(bundle, ["schema_version", "bundle_id", "version", "organization_id", "generated_at", "expires_at", "modules", "integrity"], "$", errors);
+  exactKeys(bundle, ["schema_version", "bundle_id", "version", "organization_id", "generated_at", "expires_at", "modules", "integrity", "system_scope"], "$", errors);
   equal(bundle?.schema_version, "1.0.0", "$.schema_version", errors);
   stringPattern(bundle?.bundle_id, /^[a-z][a-z0-9._-]{2,127}$/, "$.bundle_id", errors);
   stringPattern(bundle?.version, /^[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.[0-9]+$/, "$.version", errors);
   nullableString(bundle?.organization_id, 200, "$.organization_id", errors);
   dateTime(bundle?.generated_at, "$.generated_at", errors);
   dateTime(bundle?.expires_at, "$.expires_at", errors);
+  if (bundle?.system_scope !== undefined) {
+    const scope = bundle.system_scope;
+    object(scope, "$.system_scope", errors);
+    exactKeys(scope, ["organization_id", "repository", "graph_revision", "repositories"], "$.system_scope", errors);
+    equal(scope?.organization_id, bundle.organization_id, "$.system_scope.organization_id", errors);
+    stringPattern(scope?.repository, REPOSITORY, "$.system_scope.repository", errors);
+    if (!Number.isSafeInteger(scope?.graph_revision) || scope.graph_revision < 0) errors.push("$.system_scope.graph_revision must be a nonnegative integer");
+    if (!Array.isArray(scope?.repositories) || !scope.repositories.length || !scope.repositories.includes(scope.repository)) {
+      errors.push("$.system_scope.repositories must contain the target repository");
+    } else {
+      for (const repo of scope.repositories) stringPattern(repo, REPOSITORY, "$.system_scope.repositories[]", errors);
+      if (new Set(scope.repositories).size !== scope.repositories.length) errors.push("$.system_scope.repositories must be unique");
+    }
+  }
   if (!Array.isArray(bundle?.modules)) errors.push("$.modules must be an array");
   for (const [index, module] of (bundle?.modules || []).entries()) {
     validateModule(module, `$.modules[${index}]`, errors, cliVersion);

package/src/sqm/workflow-onboarding.js

@@ -36,6 +36,11 @@ export async function prepareDaemonWorkflows({
   }
   if (status.installed) return { outcome: "already_installed", status };
   if (promptDisabled) return { outcome: "skipped", status };
+  if (!installRequested && Object.values(status.platforms).some((entry) => entry.state !== "missing")) {
+    // Existing installations are maintained by the daemon; do not prompt to add
+    // a missing platform or ask again after every bundled workflow update.
+    return { outcome: "update_pending", status };
+  }
 
   if (!installRequested && (!stdinIsTTY || !stdoutIsTTY)) {
     logger(
@@ -53,7 +58,7 @@ export async function prepareDaemonWorkflows({
   try {
     const installed = await install();
     logger(
-      "SIMY workflows installed. Restart Codex, then install SIMY from Plugins > Personal before using @simy.",
+      "SIMY workflows installed. Restart Codex, then find and install SIMY in Plugins before using @simy.",
     );
     return { outcome: "installed", status: installed };
   } catch (error) {

package/src/sqm/workflow-update.js

@@ -0,0 +1,90 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { resolveBackendExecutable } from "../backend-executable.js";
+import { inspectSqmAgentSkill, installSqmAgentSkill } from "./agent-skill.js";
+
+const execFileAsync = promisify(execFile);
+const CHECK_INTERVAL_MS = 60 * 60 * 1000;
+
+export function startWorkflowUpdates({ enabled, sync = syncInstalledWorkflows, intervalMs = CHECK_INTERVAL_MS,
+  errorLogger = console.error } = {}) {
+  let pending;
+  let stopped = !enabled;
+  const check = () => {
+    if (stopped || pending) return;
+    pending = Promise.resolve().then(sync).catch((error) => {
+      errorLogger(`SIMY workflow update failed; will retry later: ${error.message}`);
+    }).finally(() => { pending = null; });
+  };
+  const timer = enabled ? setInterval(check, intervalMs) : null;
+  timer?.unref?.();
+  check();
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    await pending;
+  };
+}
+
+export async function syncInstalledWorkflows({ home = homedir(),
+  codexHome = process.env.CODEX_HOME || path.join(home, ".codex"),
+  inspect = inspectSqmAgentSkill, install = installSqmAgentSkill,
+  resolveExecutable = resolveBackendExecutable, run = execFileAsync,
+} = {}) {
+  // Multiple daemons may share the same installation. Serialize updates and recover
+  // an abandoned lock after more than the bounded Codex command timeouts.
+  const lock = path.join(home, ".simy", "integrations", "workflow-update.lock");
+  await mkdir(path.dirname(lock), { recursive: true });
+  try {
+    if (Date.now() - (await stat(lock)).mtimeMs > 5 * 60 * 1000) await rm(lock, { recursive: true, force: true });
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  try { await mkdir(lock); } catch (error) {
+    if (error.code === "EEXIST") return { outcome: "busy" };
+    throw error;
+  }
+  try {
+    let status = await inspect({ home });
+    const platforms = Object.entries(status.platforms)
+      .filter(([, entry]) => entry.state === "outdated").map(([platform]) => platform);
+    if (platforms.length) status = await install({ home, platforms });
+    if (!status.platforms.codex.installed) return { outcome: platforms.length ? "updated" : "unchanged" };
+
+    const marketplace = JSON.parse(await readFile(status.codex_plugin.marketplace_path, "utf8"));
+    if (typeof marketplace.name !== "string" || !/^[A-Za-z0-9_-]+$/.test(marketplace.name)) {
+      throw new Error("Invalid SIMY marketplace name.");
+    }
+    const executable = await resolveExecutable("codex");
+    if (!executable) throw new Error("Codex CLI is unavailable; plugin cache refresh is pending.");
+    const options = { timeout: 10_000, maxBuffer: 1024 * 1024,
+      env: { ...process.env, HOME: home, CODEX_HOME: codexHome } };
+    const list = async () => JSON.parse((await run(executable,
+      ["plugin", "list", "--marketplace", marketplace.name, "--json"], options)).stdout);
+    const selector = `simy@${marketplace.name}`;
+    const installed = (await list()).installed?.find((entry) => entry.pluginId === selector);
+    // Source installation is distinct from a user's enabled Codex plugin.
+    if (!installed?.installed || !installed.enabled) return { outcome: "not_enabled" };
+    if (installed.source?.source !== "local" ||
+        await realpath(installed.source.path) !== await realpath(status.codex_plugin.path)) {
+      throw new Error("Installed SIMY plugin points to a different source; cache refresh skipped.");
+    }
+    const cacheManifest = path.join(codexHome, "plugins", "cache", marketplace.name,
+      "simy", status.codex_plugin.version, ".codex-plugin", "plugin.json");
+    const cacheCurrent = async () => {
+      try { return JSON.parse(await readFile(cacheManifest, "utf8")).version === status.codex_plugin.version; }
+      catch (error) { if (error.code === "ENOENT" || error instanceof SyntaxError) return false; throw error; }
+    };
+    if (installed.version === status.codex_plugin.version && await cacheCurrent()) return { outcome: "current" };
+    await run(executable, ["plugin", "add", selector, "--json"], options);
+    const refreshed = (await list()).installed?.find((entry) => entry.pluginId === selector);
+    if (!refreshed?.enabled || refreshed.version !== status.codex_plugin.version || !await cacheCurrent()) {
+      throw new Error("Codex did not confirm the updated SIMY plugin cache; will retry.");
+    }
+    return { outcome: "updated", version: status.codex_plugin.version };
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}