@agimon-ai/po 0.0.0-alpha.0

package/dist/src/builders/server/backgroundSync.cjs

@@ -0,0 +1,333 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+require("../../composition/harnessState/index.cjs");
+const require_entryResolution = require("../cli/entryResolution.cjs");
+const require_index$1 = require("../../composition/layerPackageInstaller/index.cjs");
+const require_index$2 = require("../../composition/syncService/index.cjs");
+let node_fs = require("node:fs");
+node_fs = require_runtime.__toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let node_child_process = require("node:child_process");
+let _agimon_ai_po_config_harnessStore = require("@agimon-ai/po-config/harnessStore");
+let _agimon_ai_po_config_harnessState = require("@agimon-ai/po-config/harnessState");
+//#region src/builders/server/backgroundSync.ts
+/**
+* Background sync: hosts that only read what sync prepared start `po sync --json --global` as
+* a child process when a root is out of date, and pick its artifacts up when it exits. The
+* terminal app instead syncs from its repository without `--global`, which registers it.
+*
+* At most one job runs per host. Requests that arrive while it runs merge into one rerun, and
+* nothing waits on a job, so admission and session open never block on sync.
+*
+* ponytail: there is no fs.watch on `.po`, so a config edit syncs at the next checkpoint
+* (server start, admission, session open). Add a watcher if edits must apply sooner.
+*/
+/** Set on every background sync child to the pid of the host that started it. */
+const SYNC_PARENT_PID_ENV = "PO_SYNC_PARENT_PID";
+/** `PO_AUTO_SYNC=0` turns background sync off, for CI and the system test. */
+const AUTO_SYNC_ENV = "PO_AUTO_SYNC";
+const AUTO_SYNC_OFF = "0";
+const ROOT_ENV = "PO_ROOT";
+const SYNC_ARGS = ["sync", "--json"];
+const GLOBAL_OPTION = "--global";
+const CLI_ENTRY_SEGMENTS = [
+	"dist",
+	"bin",
+	"cli.mjs"
+];
+/** The host pid a sync child was started by, or undefined when this process is not one. */
+function syncParentPid(environment) {
+	const pid = Number(environment[SYNC_PARENT_PID_ENV]);
+	return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+}
+/**
+* The environment a sync child runs under, and the one a host compares root fingerprints
+* with: no harness state and no root of the host's own, so both resolve every root alike.
+*/
+function syncEnvironment(environment) {
+	const scoped = { ...environment };
+	for (const key of [
+		ROOT_ENV,
+		_agimon_ai_po_config_harnessStore.HARNESS_STATE_POINTER,
+		...Object.values(_agimon_ai_po_config_harnessState.HARNESS_STATE_KEYS)
+	]) delete scoped[key];
+	return scoped;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** Whether this host may start background sync: on unless `PO_AUTO_SYNC=0`, and never inside a sync child. */
+function autoSyncEnabled(environment) {
+	return environment["PO_AUTO_SYNC"] !== AUTO_SYNC_OFF && syncParentPid(environment) === void 0;
+}
+function createBackgroundSync(options) {
+	const enabled = autoSyncEnabled(options.environment);
+	let running = false;
+	let rerun = false;
+	const waiters = [];
+	const settle = () => {
+		if (!running) for (const resolve of waiters.splice(0)) resolve();
+	};
+	const start = () => {
+		const entry = options.cliEntry ?? node_path.default.join(require_entryResolution.poPackageRoot(), ...CLI_ENTRY_SEGMENTS);
+		if (!node_fs.default.existsSync(entry)) {
+			options.onNotice(`Background sync is unavailable because '${entry}' is missing; run po sync.`);
+			return false;
+		}
+		let child;
+		try {
+			const scope = options.repoRoot === void 0 ? [GLOBAL_OPTION] : [];
+			child = (options.spawn ?? node_child_process.spawn)(process.execPath, [
+				...process.execArgv,
+				entry,
+				...SYNC_ARGS,
+				...scope
+			], {
+				...options.repoRoot === void 0 ? {} : { cwd: options.repoRoot },
+				env: {
+					...syncEnvironment(options.environment),
+					[SYNC_PARENT_PID_ENV]: String(options.parentPid ?? process.pid)
+				},
+				stdio: "ignore",
+				detached: options.detached === true,
+				windowsHide: true
+			});
+		} catch (error) {
+			options.onNotice(`Background sync could not start: ${errorMessage(error)}`);
+			return false;
+		}
+		running = true;
+		if (options.detached === true) child.unref();
+		let finished = false;
+		const finish = (code) => {
+			if (finished) return;
+			finished = true;
+			if (code !== null && code !== 0 && code !== 75) options.onNotice(`Background sync exited with code ${String(code)}.`);
+			Promise.resolve().then(() => options.onExit?.(code)).catch((error) => options.onNotice(`Picking up background sync failed: ${errorMessage(error)}`)).finally(() => {
+				running = false;
+				if (rerun) {
+					rerun = false;
+					start();
+				}
+				settle();
+			});
+		};
+		child.once("error", (error) => {
+			options.onNotice(`Background sync could not start: ${error.message}`);
+			finish(null);
+		});
+		child.once("exit", (code) => finish(code));
+		return true;
+	};
+	return {
+		request() {
+			if (!enabled) return false;
+			if (running) {
+				rerun = true;
+				return true;
+			}
+			return start();
+		},
+		get syncing() {
+			return running || rerun;
+		},
+		idle() {
+			return new Promise((resolve) => {
+				waiters.push(resolve);
+				settle();
+			});
+		}
+	};
+}
+/**
+* Publishes a build only when the key it is given differs from the last one published, so a
+* sync that changed nothing republishes nothing. A key whose build cannot be read is skipped.
+*/
+function createKeyedPickup(read, publish) {
+	let current;
+	return (key) => {
+		if (key === null || key === void 0 || key === current) return "unchanged";
+		const build = read(key);
+		if (build === void 0) return "missing";
+		current = key;
+		publish(build, key);
+		return "published";
+	};
+}
+/**
+* The build keys a host publishes. Its own pointer names them. Before sync ever wrote one (the
+* first start after an upgrade), this install's derived keys, else the newest web build. A
+* pointer another Po install wrote is refused: what the host already publishes stays (an
+* undefined key changes nothing), and a kind it has not published yet takes only this
+* install's own build while its own sync runs, never the other install's.
+*/
+function syncedBuildKeys(input) {
+	const { pointer, published } = input;
+	if (input.ownsPointer && pointer !== void 0) return {
+		webKey: pointer.webKey,
+		nativeKey: pointer.nativeKey
+	};
+	if (pointer === void 0) {
+		const own = input.ownKeys();
+		return {
+			webKey: own.webKey ?? input.newestWebKey(),
+			nativeKey: own.nativeKey
+		};
+	}
+	if (published.web && published.native) return {
+		webKey: void 0,
+		nativeKey: void 0
+	};
+	const own = input.ownKeys();
+	return {
+		webKey: published.web ? void 0 : own.webKey,
+		nativeKey: published.native ? void 0 : own.nativeKey
+	};
+}
+/**
+* The checkpoints a host runs when it admits a root or opens a session: request a background
+* job when the root changed since the last sync, and warn about what it opened without. Each
+* root's warning is emitted once until it changes.
+*/
+function createSyncCheckpoints(input) {
+	const fingerprintEnvironment = syncEnvironment(input.environment);
+	const warned = /* @__PURE__ */ new Map();
+	/** The state each root last requested a sync for: pointer generation, catalogue and selection. */
+	const requested = /* @__PURE__ */ new Map();
+	/** This host's install, compared with the one that wrote the pointer. */
+	const host = () => require_index$2.syncHostIdentity(input.globalRoot, fingerprintEnvironment);
+	/** The last foreign pointer (install and generation) this host warned about. */
+	let warnedTakeover;
+	/**
+	* The root's state when it is stale (no pointer, a pointer another Po install wrote, a changed
+	* catalogue, or a selection that differs from the pointer's), else undefined.
+	*
+	* A foreign pointer's state includes its generation, which every sync moves, so each takeover
+	* of the shared runtime is one new stale state and gets one resync. That settles: the resync
+	* writes this host's own pointer, which is never stale for being foreign.
+	*/
+	const staleState = (root) => {
+		const pointer = require_index$2.readSyncPointer(input.globalRoot);
+		const catalogueHash = require_index$1.packageCatalogHash(input.environment);
+		const fingerprint = require_index$2.rootSelectionFingerprint(root, input.homeDirectory, fingerprintEnvironment);
+		if (pointer !== void 0 && pointer.host !== host()) return JSON.stringify([
+			"host",
+			pointer.host ?? null,
+			pointer.generation,
+			catalogueHash,
+			fingerprint
+		]);
+		if (pointer?.catalogueHash === catalogueHash && pointer.fingerprints?.[root] === fingerprint) return void 0;
+		return JSON.stringify([
+			pointer?.generation ?? null,
+			catalogueHash,
+			fingerprint
+		]);
+	};
+	const stale = (root) => staleState(root) !== void 0;
+	/**
+	* Requests one sync per stale state of a root. A sync that ran and could not change the
+	* pointer (it failed) is not requested again until the root, the catalogue or the pointer
+	* moves, so a broken root never makes every checkpoint start another full sync.
+	*/
+	const requestIfStale = (check) => {
+		const state = staleState(check.root);
+		if (state === void 0) return false;
+		if (requested.get(check.root) === state) return true;
+		if (!input.background.request(`${check.label} changed since the last sync`)) return false;
+		requested.set(check.root, state);
+		return true;
+	};
+	/** The missing artifacts a sync was requested for, each with the pointer state it was missing under. */
+	const requestedMissing = /* @__PURE__ */ new Set();
+	/** Why the last attempt, or failing that the pointer, could not prepare each selector. */
+	const failures = (root) => {
+		const reports = [require_index$2.readSyncLastAttempt(input.globalRoot), require_index$2.readSyncPointer(input.globalRoot)];
+		const reasons = /* @__PURE__ */ new Map();
+		for (const report of reports) for (const entry of report?.roots.find((candidate) => candidate.root === root)?.unsynced ?? []) if (!reasons.has(entry.selector)) reasons.set(entry.selector, entry.reason);
+		return reasons;
+	};
+	return {
+		stale,
+		/**
+		* Whether this host may publish the builds `pointer` names: only when its own Po install wrote
+		* it. Every pointer another install writes (each sync moves its generation) is refused, and
+		* gets one background sync of the global root and one warning, so this host keeps its previous
+		* publication until its own sync replaces the pointer.
+		*/
+		ownsPointer(pointer) {
+			if (pointer === void 0) return false;
+			const own = host();
+			if (pointer.host === own) return true;
+			const foreign = pointer.host ?? "an older Po";
+			const resyncing = requestIfStale({
+				root: input.globalRoot,
+				label: "The global scope",
+				unsynced: []
+			});
+			const takeover = JSON.stringify([foreign, pointer.generation]);
+			if (warnedTakeover !== takeover) {
+				warnedTakeover = takeover;
+				input.onNotice(`Another Po install (${foreign}) replaced the shared packages; ${resyncing ? `resyncing with this install (${own})` : "run po sync from this install to resync"}. Use one Po install so they stop replacing each other.`);
+			}
+			return false;
+		},
+		/**
+		* Requests one sync per missing artifact (such as an MCP app build key) and pointer state,
+		* the same limit stale roots get: a sync that ran and still did not produce it is not
+		* requested again until the pointer or the catalogue moves.
+		*/
+		requestMissing(artifact, reason) {
+			const pointer = require_index$2.readSyncPointer(input.globalRoot);
+			const state = JSON.stringify([
+				artifact,
+				pointer?.generation ?? null,
+				require_index$1.packageCatalogHash(input.environment)
+			]);
+			if (requestedMissing.has(state) || !input.background.request(reason)) return false;
+			requestedMissing.add(state);
+			return true;
+		},
+		/** Requests a job when `request` allows and the root is stale, then warns about `unsynced`. */
+		check(check, request = true) {
+			if (request) requestIfStale(check);
+			const syncing = input.background.syncing;
+			if (check.unsynced.length === 0) {
+				warned.delete(check.root);
+				return {
+					syncing,
+					reasons: []
+				};
+			}
+			const known = failures(check.root);
+			const count = check.unsynced.length;
+			const noun = count === 1 ? "extension" : "extensions";
+			const reasons = check.unsynced.map((selector) => {
+				const reason = known.get(selector);
+				if (syncing || reason === void 0) return `${selector} is not synced yet`;
+				return `Sync could not prepare ${selector}: ${reason}.`;
+			});
+			const message = syncing ? `${check.label} opened without ${String(count)} ${noun} that ${count === 1 ? "is" : "are"} still syncing: ${check.unsynced.join(", ")}. ${count === 1 ? "It loads" : "They load"} when sync finishes.` : check.unsynced.every((selector) => known.has(selector)) ? reasons.join(" ") : `${check.label} opened without ${String(count)} ${noun} that ${count === 1 ? "is" : "are"} not synced: ${check.unsynced.join(", ")}. Run po sync to prepare them.`;
+			if (warned.get(check.root) !== message) {
+				warned.set(check.root, message);
+				input.onNotice(message);
+			}
+			return {
+				syncing,
+				reasons
+			};
+		}
+	};
+}
+//#endregion
+exports.AUTO_SYNC_ENV = AUTO_SYNC_ENV;
+exports.SYNC_PARENT_PID_ENV = SYNC_PARENT_PID_ENV;
+exports.autoSyncEnabled = autoSyncEnabled;
+exports.createBackgroundSync = createBackgroundSync;
+exports.createKeyedPickup = createKeyedPickup;
+exports.createSyncCheckpoints = createSyncCheckpoints;
+exports.syncEnvironment = syncEnvironment;
+exports.syncParentPid = syncParentPid;
+exports.syncedBuildKeys = syncedBuildKeys;
+
+//# sourceMappingURL=backgroundSync.cjs.map

package/dist/src/builders/server/backgroundSync.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundSync.cjs","names":["HARNESS_STATE_POINTER","HARNESS_STATE_KEYS","path","poPackageRoot","fs","spawnProcess","syncHostIdentity","readSyncPointer","packageCatalogHash","rootSelectionFingerprint","readSyncLastAttempt"],"sources":["../../../../src/builders/server/backgroundSync.ts"],"sourcesContent":["import { type ChildProcess, spawn as spawnProcess, type SpawnOptions } from 'node:child_process';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { HARNESS_STATE_KEYS, HARNESS_STATE_POINTER } from '../../composition/harnessState';\nimport { packageCatalogHash } from '../../composition/layerPackageInstaller';\nimport {\n  readSyncLastAttempt,\n  readSyncPointer,\n  rootSelectionFingerprint,\n  SYNC_EXIT_BUSY,\n  SYNC_EXIT_OK,\n  type SyncPointer,\n  syncHostIdentity,\n} from '../../composition/syncService';\nimport { poPackageRoot } from '../cli/entryResolution';\n\n/**\n * Background sync: hosts that only read what sync prepared start `po sync --json --global` as\n * a child process when a root is out of date, and pick its artifacts up when it exits. The\n * terminal app instead syncs from its repository without `--global`, which registers it.\n *\n * At most one job runs per host. Requests that arrive while it runs merge into one rerun, and\n * nothing waits on a job, so admission and session open never block on sync.\n *\n * ponytail: there is no fs.watch on `.po`, so a config edit syncs at the next checkpoint\n * (server start, admission, session open). Add a watcher if edits must apply sooner.\n */\n\n/** Set on every background sync child to the pid of the host that started it. */\nexport const SYNC_PARENT_PID_ENV = 'PO_SYNC_PARENT_PID';\n/** `PO_AUTO_SYNC=0` turns background sync off, for CI and the system test. */\nexport const AUTO_SYNC_ENV = 'PO_AUTO_SYNC';\nconst AUTO_SYNC_OFF = '0';\nconst ROOT_ENV = 'PO_ROOT';\nconst SYNC_ARGS = ['sync', '--json'] as const;\nconst GLOBAL_OPTION = '--global';\nconst CLI_ENTRY_SEGMENTS = ['dist', 'bin', 'cli.mjs'] as const;\n\n/** The host pid a sync child was started by, or undefined when this process is not one. */\nexport function syncParentPid(environment: NodeJS.ProcessEnv): number | undefined {\n  const pid = Number(environment[SYNC_PARENT_PID_ENV]);\n  return Number.isInteger(pid) && pid > 0 ? pid : undefined;\n}\n\n/**\n * The environment a sync child runs under, and the one a host compares root fingerprints\n * with: no harness state and no root of the host's own, so both resolve every root alike.\n */\nexport function syncEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n  const scoped = { ...environment };\n  for (const key of [ROOT_ENV, HARNESS_STATE_POINTER, ...Object.values(HARNESS_STATE_KEYS)]) delete scoped[key];\n  return scoped;\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nexport interface BackgroundSyncOptions {\n  environment: NodeJS.ProcessEnv;\n  onNotice: (message: string) => void;\n  /** Runs after each job's child exits, before a merged rerun starts. */\n  onExit?: (code: number | null) => void | Promise<void>;\n  /** Lets the child outlive this process, for a terminal app that exits before sync finishes. */\n  detached?: boolean;\n  /**\n   * The repository the child syncs from, without `--global`, so sync registers it as a workspace.\n   * Without one the child runs with `--global` and registers nothing.\n   */\n  repoRoot?: string;\n  /** Test seams. */\n  spawn?: (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;\n  cliEntry?: string;\n  parentPid?: number;\n}\n\nexport interface BackgroundSync {\n  /** Starts a job, or merges into the rerun of the running one. False when background sync is off. */\n  request(reason: string): boolean;\n  /** Whether a job runs or a rerun is queued. */\n  readonly syncing: boolean;\n  /** Resolves once no job runs and none is queued. */\n  idle(): Promise<void>;\n}\n\n/** Whether this host may start background sync: on unless `PO_AUTO_SYNC=0`, and never inside a sync child. */\nexport function autoSyncEnabled(environment: NodeJS.ProcessEnv): boolean {\n  return environment[AUTO_SYNC_ENV] !== AUTO_SYNC_OFF && syncParentPid(environment) === undefined;\n}\n\nexport function createBackgroundSync(options: BackgroundSyncOptions): BackgroundSync {\n  const enabled = autoSyncEnabled(options.environment);\n  let running = false;\n  let rerun = false;\n  const waiters: (() => void)[] = [];\n  const settle = (): void => {\n    if (!running) for (const resolve of waiters.splice(0)) resolve();\n  };\n  const start = (): boolean => {\n    const entry = options.cliEntry ?? path.join(poPackageRoot(), ...CLI_ENTRY_SEGMENTS);\n    if (!fs.existsSync(entry)) {\n      options.onNotice(`Background sync is unavailable because '${entry}' is missing; run po sync.`);\n      return false;\n    }\n    let child: ChildProcess;\n    try {\n      // On desktop the child inherits ELECTRON_RUN_AS_NODE, so the app binary runs it as node.\n      const scope = options.repoRoot === undefined ? [GLOBAL_OPTION] : [];\n      child = (options.spawn ?? spawnProcess)(process.execPath, [...process.execArgv, entry, ...SYNC_ARGS, ...scope], {\n        ...(options.repoRoot === undefined ? {} : { cwd: options.repoRoot }),\n        env: {\n          ...syncEnvironment(options.environment),\n          [SYNC_PARENT_PID_ENV]: String(options.parentPid ?? process.pid),\n        },\n        stdio: 'ignore',\n        detached: options.detached === true,\n        windowsHide: true,\n      });\n    } catch (error) {\n      options.onNotice(`Background sync could not start: ${errorMessage(error)}`);\n      return false;\n    }\n    running = true;\n    if (options.detached === true) child.unref();\n    let finished = false;\n    const finish = (code: number | null): void => {\n      if (finished) return;\n      finished = true;\n      if (code !== null && code !== SYNC_EXIT_OK && code !== SYNC_EXIT_BUSY)\n        options.onNotice(`Background sync exited with code ${String(code)}.`);\n      void Promise.resolve()\n        .then(() => options.onExit?.(code))\n        .catch((error: unknown) => options.onNotice(`Picking up background sync failed: ${errorMessage(error)}`))\n        .finally(() => {\n          running = false;\n          if (rerun) {\n            rerun = false;\n            start();\n          }\n          settle();\n        });\n    };\n    child.once('error', (error) => {\n      options.onNotice(`Background sync could not start: ${error.message}`);\n      finish(null);\n    });\n    child.once('exit', (code) => finish(code));\n    return true;\n  };\n  return {\n    request(): boolean {\n      if (!enabled) return false;\n      if (running) {\n        rerun = true;\n        return true;\n      }\n      return start();\n    },\n    get syncing() {\n      return running || rerun;\n    },\n    idle() {\n      return new Promise<void>((resolve) => {\n        waiters.push(resolve);\n        settle();\n      });\n    },\n  };\n}\n\n/**\n * Publishes a build only when the key it is given differs from the last one published, so a\n * sync that changed nothing republishes nothing. A key whose build cannot be read is skipped.\n */\nexport function createKeyedPickup<T>(\n  read: (key: string) => T | undefined,\n  publish: (build: T, key: string) => void,\n): (key: string | null | undefined) => 'published' | 'unchanged' | 'missing' {\n  let current: string | undefined;\n  return (key) => {\n    if (key === null || key === undefined || key === current) return 'unchanged';\n    const build = read(key);\n    if (build === undefined) return 'missing';\n    current = key;\n    publish(build, key);\n    return 'published';\n  };\n}\n\nexport interface SyncedBuildKeys {\n  webKey: string | null | undefined;\n  nativeKey: string | null | undefined;\n}\n\nexport interface SyncedBuildKeysInput {\n  pointer: SyncPointer | undefined;\n  /** Whether this host's own Po install wrote `pointer`. */\n  ownsPointer: boolean;\n  /** The kinds this host already publishes. */\n  published: { web: boolean; native: boolean };\n  /** The keys this install derives the way sync does, each only when its build exists. */\n  ownKeys: () => { webKey?: string; nativeKey?: string };\n  /** The newest web build in the Po home, whichever install made it. */\n  newestWebKey: () => string | undefined;\n}\n\n/**\n * The build keys a host publishes. Its own pointer names them. Before sync ever wrote one (the\n * first start after an upgrade), this install's derived keys, else the newest web build. A\n * pointer another Po install wrote is refused: what the host already publishes stays (an\n * undefined key changes nothing), and a kind it has not published yet takes only this\n * install's own build while its own sync runs, never the other install's.\n */\nexport function syncedBuildKeys(input: SyncedBuildKeysInput): SyncedBuildKeys {\n  const { pointer, published } = input;\n  if (input.ownsPointer && pointer !== undefined) return { webKey: pointer.webKey, nativeKey: pointer.nativeKey };\n  if (pointer === undefined) {\n    const own = input.ownKeys();\n    return { webKey: own.webKey ?? input.newestWebKey(), nativeKey: own.nativeKey };\n  }\n  if (published.web && published.native) return { webKey: undefined, nativeKey: undefined };\n  const own = input.ownKeys();\n  return {\n    webKey: published.web ? undefined : own.webKey,\n    nativeKey: published.native ? undefined : own.nativeKey,\n  };\n}\n\nexport interface SyncCheckpointsInput {\n  globalRoot: string;\n  homeDirectory: string;\n  environment: NodeJS.ProcessEnv;\n  background: BackgroundSync;\n  onNotice: (message: string) => void;\n}\n\nexport interface RootSyncCheck {\n  root: string;\n  /** How the root is named in a warning, such as `Workspace 'po'`. */\n  label: string;\n  /** The selectors this host left out because they are not synced. */\n  unsynced: readonly string[];\n}\n\nexport interface RootSyncStatus {\n  syncing: boolean;\n  /** One line per unsynced selector: why sync could not prepare it, or that it is still syncing. */\n  reasons: string[];\n}\n\n/**\n * The checkpoints a host runs when it admits a root or opens a session: request a background\n * job when the root changed since the last sync, and warn about what it opened without. Each\n * root's warning is emitted once until it changes.\n */\nexport function createSyncCheckpoints(input: SyncCheckpointsInput) {\n  const fingerprintEnvironment = syncEnvironment(input.environment);\n  const warned = new Map<string, string>();\n  /** The state each root last requested a sync for: pointer generation, catalogue and selection. */\n  const requested = new Map<string, string>();\n  /** This host's install, compared with the one that wrote the pointer. */\n  const host = (): string => syncHostIdentity(input.globalRoot, fingerprintEnvironment);\n  /** The last foreign pointer (install and generation) this host warned about. */\n  let warnedTakeover: string | undefined;\n  /**\n   * The root's state when it is stale (no pointer, a pointer another Po install wrote, a changed\n   * catalogue, or a selection that differs from the pointer's), else undefined.\n   *\n   * A foreign pointer's state includes its generation, which every sync moves, so each takeover\n   * of the shared runtime is one new stale state and gets one resync. That settles: the resync\n   * writes this host's own pointer, which is never stale for being foreign.\n   */\n  const staleState = (root: string): string | undefined => {\n    const pointer = readSyncPointer(input.globalRoot);\n    const catalogueHash = packageCatalogHash(input.environment);\n    const fingerprint = rootSelectionFingerprint(root, input.homeDirectory, fingerprintEnvironment);\n    if (pointer !== undefined && pointer.host !== host())\n      return JSON.stringify(['host', pointer.host ?? null, pointer.generation, catalogueHash, fingerprint]);\n    if (pointer?.catalogueHash === catalogueHash && pointer.fingerprints?.[root] === fingerprint) return undefined;\n    return JSON.stringify([pointer?.generation ?? null, catalogueHash, fingerprint]);\n  };\n  const stale = (root: string): boolean => staleState(root) !== undefined;\n  /**\n   * Requests one sync per stale state of a root. A sync that ran and could not change the\n   * pointer (it failed) is not requested again until the root, the catalogue or the pointer\n   * moves, so a broken root never makes every checkpoint start another full sync.\n   */\n  const requestIfStale = (check: RootSyncCheck): boolean => {\n    const state = staleState(check.root);\n    if (state === undefined) return false;\n    if (requested.get(check.root) === state) return true;\n    if (!input.background.request(`${check.label} changed since the last sync`)) return false;\n    requested.set(check.root, state);\n    return true;\n  };\n  /** The missing artifacts a sync was requested for, each with the pointer state it was missing under. */\n  const requestedMissing = new Set<string>();\n  /** Why the last attempt, or failing that the pointer, could not prepare each selector. */\n  const failures = (root: string): Map<string, string> => {\n    const reports = [readSyncLastAttempt(input.globalRoot), readSyncPointer(input.globalRoot)];\n    const reasons = new Map<string, string>();\n    for (const report of reports)\n      for (const entry of report?.roots.find((candidate) => candidate.root === root)?.unsynced ?? [])\n        if (!reasons.has(entry.selector)) reasons.set(entry.selector, entry.reason);\n    return reasons;\n  };\n  return {\n    stale,\n    /**\n     * Whether this host may publish the builds `pointer` names: only when its own Po install wrote\n     * it. Every pointer another install writes (each sync moves its generation) is refused, and\n     * gets one background sync of the global root and one warning, so this host keeps its previous\n     * publication until its own sync replaces the pointer.\n     */\n    ownsPointer(pointer: SyncPointer | undefined): pointer is SyncPointer {\n      if (pointer === undefined) return false;\n      const own = host();\n      if (pointer.host === own) return true;\n      const foreign = pointer.host ?? 'an older Po';\n      const resyncing = requestIfStale({ root: input.globalRoot, label: 'The global scope', unsynced: [] });\n      const takeover = JSON.stringify([foreign, pointer.generation]);\n      if (warnedTakeover !== takeover) {\n        warnedTakeover = takeover;\n        input.onNotice(\n          `Another Po install (${foreign}) replaced the shared packages; ${resyncing ? `resyncing with this install (${own})` : 'run po sync from this install to resync'}. Use one Po install so they stop replacing each other.`,\n        );\n      }\n      return false;\n    },\n    /**\n     * Requests one sync per missing artifact (such as an MCP app build key) and pointer state,\n     * the same limit stale roots get: a sync that ran and still did not produce it is not\n     * requested again until the pointer or the catalogue moves.\n     */\n    requestMissing(artifact: string, reason: string): boolean {\n      const pointer = readSyncPointer(input.globalRoot);\n      const state = JSON.stringify([artifact, pointer?.generation ?? null, packageCatalogHash(input.environment)]);\n      if (requestedMissing.has(state) || !input.background.request(reason)) return false;\n      requestedMissing.add(state);\n      return true;\n    },\n    /** Requests a job when `request` allows and the root is stale, then warns about `unsynced`. */\n    check(check: RootSyncCheck, request = true): RootSyncStatus {\n      if (request) requestIfStale(check);\n      const syncing = input.background.syncing;\n      if (check.unsynced.length === 0) {\n        warned.delete(check.root);\n        return { syncing, reasons: [] };\n      }\n      const known = failures(check.root);\n      const count = check.unsynced.length;\n      const noun = count === 1 ? 'extension' : 'extensions';\n      const reasons = check.unsynced.map((selector) => {\n        const reason = known.get(selector);\n        if (syncing || reason === undefined) return `${selector} is not synced yet`;\n        return `Sync could not prepare ${selector}: ${reason}.`;\n      });\n      const message = syncing\n        ? `${check.label} opened without ${String(count)} ${noun} that ${count === 1 ? 'is' : 'are'} still syncing: ${check.unsynced.join(', ')}. ${count === 1 ? 'It loads' : 'They load'} when sync finishes.`\n        : check.unsynced.every((selector) => known.has(selector))\n          ? reasons.join(' ')\n          : `${check.label} opened without ${String(count)} ${noun} that ${count === 1 ? 'is' : 'are'} not synced: ${check.unsynced.join(', ')}. Run po sync to prepare them.`;\n      if (warned.get(check.root) !== message) {\n        warned.set(check.root, message);\n        input.onNotice(message);\n      }\n      return { syncing, reasons };\n    },\n  };\n}\n"],"mappings":"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"}