sprag-cli 3.69.0 → 3.71.0

package/src/env.js

@@ -0,0 +1,19 @@
+/**
+ * Reads a SPRAG_ environment variable, falling back to its legacy CTS_ name.
+ *
+ * The package used to be called claude-token-saver and its variables carried a
+ * CTS_ prefix. Users still have those set in shells, CI and Claude Code managed
+ * settings, so every read takes the SPRAG_ name first and the CTS_ name second.
+ * Pass the suffix: envVar('NO_TEAM_SYNC') answers env.SPRAG_NO_TEAM_SYNC ??
+ * env.CTS_NO_TEAM_SYNC.
+ *
+ * src/env.cjs is the CommonJS twin for the .cjs files; test/env.test.js pins
+ * the two together.
+ *
+ * @param {string} name the variable name without its prefix
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string | undefined}
+ */
+export function envVar(name, env = process.env) {
+  return env['SPRAG_' + name] ?? env['CTS_' + name];
+}

package/src/first-run-note.js

@@ -5,10 +5,11 @@
  * ONCE per note key and then never again: the shown-at timestamp is persisted
  * next to the other state files and checked before anything is printed.
  *
- * Opt out entirely with CTS_NO_NOTE=1 (also honoured by anything that pipes
+ * Opt out entirely with SPRAG_NO_NOTE=1 (also honoured by anything that pipes
  * our output somewhere it does not belong).
  */
 
+import { envVar } from './env.js';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
@@ -53,7 +54,7 @@ export function markNoteShown(key, now = Date.now()) {
 /** True only the first time this key is asked about. Best-effort — a
  *  read-only state dir just means the note repeats, never that we crash. */
 export function shouldShowOnce(key, { now = Date.now() } = {}) {
-  if (process.env.CTS_NO_NOTE === '1') return false;
+  if (envVar('NO_NOTE') === '1') return false;
   if (load()[key]) return false;
   try {
     markShown(key, now);

package/src/harness-templates.js

@@ -52,6 +52,16 @@ export function presetRatchetImportLine() {
 }
 export const PRESET_RATCHET_IMPORT_RE = /^@~\/\.claude\/ratchet-preset\.md\s*$/m;
 
+/**
+ * The team ratchet: rules the user's team approved, cached by `sprag team sync`
+ * and rendered into a tool-owned file. Unlike the others its import is not in
+ * the rendered block; it is added only for members, when the file exists.
+ */
+export function teamRatchetImportLine() {
+  return '@~/.claude/ratchet-team.md';
+}
+export const TEAM_RATCHET_IMPORT_RE = /^@~\/\.claude\/ratchet-team\.md\s*$/m;
+
 /**
  * Render ratchet-preset.md. `rules` is [{ id, text }] in display order. The
  * file is loaded into every session, so the header stays short.

package/src/harness.js

@@ -11,7 +11,6 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'no
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
 import {
   HARNESS_SECTIONS,
   HARNESS_BLOCK_BEGIN,
@@ -28,6 +27,7 @@ import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet
 import { compactWindowWarningForStatusline } from './compact-window.js';
 import { userLanguage } from './config.js';
 import { codexUserDir } from './agent.js';
+import { ratchetPresetEntries } from './presets-source.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -441,19 +441,9 @@ export async function harnessPull({ root = findProjectRoot(), scope = 'global',
  * turns a rule the user already answered into a new one.
  */
 export function presetRuleEntries() {
-  try {
-    // fileURLToPath, not `.pathname`: the latter yields `/D:/repo/src` on
-    // Windows, where the read fails and the catch below turns a missing
-    // file into an empty rule set without ever saying so.
-    const path = join(dirname(fileURLToPath(import.meta.url)), '..', 'presets', 'ratchet-rules.json');
-    const data = JSON.parse(readFileSync(path, 'utf8'));
-    return (Array.isArray(data.rules) ? data.rules : [])
-      .filter((r) => r && typeof r.ko === 'string' && r.ko.trim())
-      .map((r) => ({ ko: r.ko.trim(), en: (r.en || r.ko).trim(),
-        ...(Array.isArray(r.agents) ? { agents: r.agents.filter((a) => typeof a === 'string') } : {}) }));
-  } catch {
-    return [];
-  }
+  // The published bundle when it verifies, else presets/ratchet-rules.json
+  // (presets-source.js). Each entry carries its stable id.
+  return ratchetPresetEntries();
 }
 
 /** Preset rule text in the user's configured language. */

package/src/hook.cjs

@@ -13,11 +13,12 @@
 'use strict';
 
 // CJS twin of src/debug.js \u2014 hook failures must stay silent for the session
-// but be visible under CTS_DEBUG=1, otherwise a broken path is
+// but be visible under SPRAG_DEBUG=1, otherwise a broken path is
 // indistinguishable from "nothing to do".
-var CTS_DEBUG = !!process.env.CTS_DEBUG;
+// Standalone hook (no requires), so the SPRAG_ -> CTS_ fallback is inline.
+var DEBUG_ON = !!(process.env.SPRAG_DEBUG ?? process.env.CTS_DEBUG);
 function dbg(scope, err) {
-  if (!CTS_DEBUG) return;
+  if (!DEBUG_ON) return;
   process.stderr.write('[cts:' + scope + '] ' + ((err && err.stack) || String(err)) + '\n');
 }
 

package/src/model-rules.js

@@ -72,7 +72,8 @@ export function wilsonLowerBound(errs, n) {
 // route-scan's pre-calibration defaults. Kept as local constants rather than
 // imported: route-scan imports this module, and a static back-import would
 // close the cycle.
-const DEFAULT_BUDGET = { T2: { calls: 8, out: 1500 }, T1: { calls: null, out: 8000 } };
+const DEFAULT_BUDGET = { T2: { calls: 8, out: 1500 }, T1: { calls: null, out: 8000 },
+  T1H: { calls: null, out: 30000 } };
 
 /** The budget a rule is held to: its calibrated one, or the default of its tier. */
 export function ruleBudget(rule) {
@@ -132,20 +133,27 @@ function shortExample(text) {
   return one.length <= EXAMPLE_MAX ? one : `${one.slice(0, EXAMPLE_MAX - 1)}…`;
 }
 
-// T1 is named through its delegation agent only when that file exists; without
-// it the literal `model: sonnet` stays so output on such machines is unchanged.
-function t1Target(root, ko) {
-  if (resolveAgentName('sonnet', root) === null) return null;
-  return (ko ? agentPhrase : agentPhraseEn)('sonnet', { root });
+// T1 (and T1H) is named through its delegation agent only when that file
+// exists; without it the literal `model: sonnet` / `model: opus` stays so
+// output on such machines is unchanged.
+function t1Target(root, ko, tier = 'sonnet') {
+  if (resolveAgentName(tier, root) === null) return null;
+  return (ko ? agentPhrase : agentPhraseEn)(tier, { root });
 }
 
 export function modelRuleBaseText(g, lang = userLanguage(), { root } = {}) {
   if (lang === 'ko') {
+    if (g.tier === 'T1H') {
+      return `"${g.label}" 고난도 구현 요청(예: "${shortExample(g.example)}")은 Fable·Mythos 세션에 한해 ${t1Target(root, true, 'opus') ?? 'model: opus'}에 위임`;
+    }
     return g.tier === 'T2'
       ? `"${g.label}" 단순 요청(예: "${shortExample(g.example)}")은 ${agentPhrase(g.agent, { root })}에 위임`
       : `"${g.label}" 중간 난도 요청(예: "${shortExample(g.example)}")은 ${t1Target(root, true) ?? 'model: sonnet'}에 위임`;
   }
   const example = g.exampleEn || g.example;
+  if (g.tier === 'T1H') {
+    return `Heavy "${g.labelEn}" implementation requests (e.g. "${shortExample(example)}") go to ${t1Target(root, false, 'opus') ?? 'a model: opus subagent'}, in Fable/Mythos sessions only`;
+  }
   return g.tier === 'T2'
     ? `Simple "${g.labelEn}" requests (e.g. "${shortExample(example)}") go to ${agentPhraseEn(g.agent, { root })}`
     : `Moderate "${g.labelEn}" requests (e.g. "${shortExample(example)}") go to ${t1Target(root, false) ?? 'a model: sonnet subagent'}`;
@@ -275,8 +283,12 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '- **effort**: 모델 티어와 다른 축이다. 설치된 서브에이전트는 검증 형태에 따라',
     '  effort가 고정되어 있다. 명령 출력이나 파일 대조로 검증되는 위임(조회·명령',
     '  실행·정형 변환을 맡는 haiku 에이전트)은 low, 확정된 설계를 테스트에 맞춰',
-    '  구현하는 위임(sonnet 워커)은 medium이다. 메인 세션의 effort는 바꾸지 않고,',
+    '  구현하는 위임(sonnet 워커)은 medium, 범위가 큰 구현·디버깅 위임(opus 워커)은',
+    '  high다. 메인 세션의 effort는 바꾸지 않고,',
     '  CLAUDE_CODE_EFFORT_LEVEL은 서브에이전트의 effort를 덮어쓰므로 설정하지 않는다.',
+    '- **고난도 구현(T1H)**: 설계는 메인이 확정하고, 범위가 크거나 sonnet 이 틀린',
+    '  적 있는 구현·디버깅은 opus 에 위임한다. Fable·Mythos 세션에서만 적용되며,',
+    '  설계 판단과 되돌릴 수 없는 작업은 메인 모델에 남긴다.',
     '- **위임 배치**: 서브에이전트 비용의 지배 항은 생성이 아니라 컨텍스트',
     '  적재다. 같은 파일들을 읽어야 하는 작업 여러 개는 에이전트 하나에 묶어',
     '  보내고, 읽는 영역이 다른 작업만 나눈다.',
@@ -337,8 +349,13 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '  by how their work is verified: low where the check is command output or a',
     '  file comparison (the haiku agents for lookups, command runs and mechanical',
     '  conversion), medium where a fixed design is implemented against tests (the',
-    '  sonnet worker). Leave the main session\'s effort alone, and never set',
+    '  sonnet worker), high for large implementation or debugging (the opus',
+    '  worker). Leave the main session\'s effort alone, and never set',
     '  CLAUDE_CODE_EFFORT_LEVEL: it overrides every subagent\'s own value.',
+    '- **Heavy implementation (T1H)**: the main model fixes the design; large-scope',
+    '  implementation or debugging, or work sonnet has already got wrong, goes to',
+    '  opus. Applies in Fable/Mythos sessions only; design judgement and',
+    '  irreversible work stay on the main model.',
     '- **Batching**: a subagent\'s dominant cost is context ingestion, not',
     '  generation. Bundle tasks that read the same files into one agent; split',
     '  only when the areas they read differ.',
@@ -384,13 +401,13 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     const saved = r.savedUsd ? `, saved ~${signedUsd(r.savedUsd)}` : '';
     return `${base}, delegated ×${r.delegatedRuns} err ${pct(r.delegatedErrRate)}%${saved}`;
   };
-  // Merged T2+T1 rules carry two caps, so they state both once rather than
+  // Merged rules carry one cap per tier, so they state them once rather than
   // repeating the whole stop-condition per tier.
-  const mergedBudget = (t2, t1) => ko
-    ? `상한 haiku ${budgetCapPhrase(t2, 'ko')} / sonnet ${budgetCapPhrase(t1, 'ko')}`
-    : `cap haiku ${budgetCapPhrase(t2, 'en')} / sonnet ${budgetCapPhrase(t1, 'en')}`;
+  const TIER_MODEL = { T2: 'haiku', T1: 'sonnet', T1H: 'opus' };
+  const mergedBudget = (tiers) => (ko ? '상한 ' : 'cap ') + tiers
+    .map((r) => `${TIER_MODEL[r.tier]} ${budgetCapPhrase(r, ko ? 'ko' : 'en')}`).join(' / ');
 
-  // A category can carry both a T2 (haiku) and a T1 (sonnet) rule. Tier is
+  // A category can carry a T2 (haiku), a T1 (sonnet) and a T1H (opus) rule. Tier is
   // only known after an episode finishes, so two separate bullets give the
   // reading LLM no way to pick one at request time — merge such pairs into a
   // single conditional rule with explicit request-time criteria (default to
@@ -405,38 +422,50 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
   // text stored on the rule is whatever wording and language were current when
   // it was promoted, which is how an English line sat in a Korean file. A rule
   // missing what the template needs still falls back to its stored text.
-  const baseTextOf = (r) => ((r.tier === 'T2' || r.tier === 'T1') && r.label && (ko || r.labelEn)
+  const baseTextOf = (r) => ((r.tier === 'T2' || r.tier === 'T1' || r.tier === 'T1H') && r.label && (ko || r.labelEn)
     ? modelRuleBaseText(r, lang, { root }) : r.rule);
+  const DELEGATION_TIERS = ['T2', 'T1', 'T1H'];
   for (const group of byCategory.values()) {
-    const t2 = group.find((r) => r.tier === 'T2');
-    const t1 = group.find((r) => r.tier === 'T1');
+    const picked = DELEGATION_TIERS.map((t) => group.find((r) => r.tier === t)).filter(Boolean);
     // A second rule of a tier the line already covers (two global rules of one
     // category, promoted from different projects) says nothing the line does
     // not, so it adds no line of its own. Its review flag and its numbers stay
     // visible on the line that speaks for it.
-    const extras = t2 || t1 ? group.filter((r) => r !== t2 && r !== t1 && (r.tier === 'T2' || r.tier === 'T1')) : [];
-    const unknown = group.filter((r) => r !== t2 && r !== t1 && !extras.includes(r));
+    const extras = picked.length ? group.filter((r) => !picked.includes(r) && DELEGATION_TIERS.includes(r.tier)) : [];
+    const unknown = group.filter((r) => !picked.includes(r) && !extras.includes(r));
     const extraHealth = extras.map(healthOf).join('');
     const extraStats = extras.map((r) => ` / +${r.tier} ${statsOf(r)}`).join('');
-    if (t2 && t1) {
+    if (picked.length >= 2) {
       // Seeded rules carry a localized example; scan-produced ones only have the
       // user's own prompt, so exampleEn is a preference, not a requirement.
       const ex = (r) => shortExample(ko ? r.example : (r.exampleEn || r.example));
-      // One line per category, stating only what differs between the two tiers.
+      const target = (r) => {
+        if (r.tier === 'T2') return (ko ? agentPhrase : agentPhraseEn)(r.agent, { root });
+        const name = r.tier === 'T1H' ? 'opus' : 'sonnet';
+        return t1Target(root, ko, name) ?? `model: ${name}`;
+      };
+      // One line per category, stating only what differs between the tiers.
       // The exceptions this used to spell out (design judgement, irreversible
       // work) are identical in every rule and now sit in the header's shared
       // clauses, so a rule the model re-reads on every request is short enough to
       // match at a glance.
+      const when = (r, first) => {
+        if (first) return ko ? '기본' : 'by default';
+        if (r.tier === 'T1H') return ko ? '범위가 크면(Fable·Mythos 세션 한정)' : 'for large scope (Fable/Mythos sessions only)';
+        return ko ? '여러 단계·여러 파일이 얽히면' : 'when it spans multiple steps or file edits';
+      };
+      const parts = picked.map((r, i) => (ko
+        ? `${when(r, i === 0)} ${target(r)}(예: "${ex(r)}")`
+        : `${i === 0 ? `${target(r)} ${when(r, true)}` : `${target(r)} ${when(r, false)}`} (e.g. "${ex(r)}")`));
+      const head = picked[0];
       const rule = ko
-        ? `"${t2.label}": 기본 ${agentPhrase(t2.agent, { root })}(예: "${ex(t2)}"), ` +
-          `여러 단계·여러 파일이 얽히면 ${t1Target(root, true) ?? 'model: sonnet'}(예: "${ex(t1)}"). ` +
-          mergedBudget(t2, t1)
-        : `"${t2.labelEn || t2.label}": ${agentPhraseEn(t2.agent, { root })} by default (e.g. "${ex(t2)}"), ` +
-          `${t1Target(root, false) ?? 'model: sonnet'} when it spans multiple steps or file edits (e.g. "${ex(t1)}"). ` +
-          mergedBudget(t2, t1);
-      lines.push(`- ${rule}${healthOf(t2)}${healthOf(t1)}${extraHealth} <!-- T2 ${statsOf(t2)} / T1 ${statsOf(t1)}${extraStats} -->`);
-    } else if (t2 || t1) {
-      const r = t2 || t1;
+        ? `"${head.label}": ${parts.join(', ')}. ${mergedBudget(picked)}`
+        : `"${head.labelEn || head.label}": ${parts.join(', ')}. ${mergedBudget(picked)}`;
+      const health = picked.map(healthOf).join('');
+      const stats = picked.map((r) => `${r.tier} ${statsOf(r)}`).join(' / ');
+      lines.push(`- ${rule}${health}${extraHealth} <!-- ${stats}${extraStats} -->`);
+    } else if (picked.length === 1) {
+      const r = picked[0];
       lines.push(`- ${composeRuleText(baseTextOf(r), r, lang)}${healthOf(r)}${extraHealth} <!-- ${statsOf(r)}${extraStats} -->`);
     }
     for (const r of unknown) lines.push(`- ${composeRuleText(r.rule, r, lang)}${healthOf(r)} <!-- ${statsOf(r)} -->`);

package/src/preset-sign.js

@@ -0,0 +1,106 @@
+/**
+ * preset-sign — the signature on a centrally published preset bundle.
+ *
+ * The superuser edits presets in the /ops console and signs each published
+ * bundle in the browser with an ECDSA P-256 key (WebCrypto, SHA-256). The CLI
+ * applies a remote bundle only when that signature verifies against a public key
+ * listed here, so a compromised server or a man in the middle cannot push
+ * ratchet text or agent prompts into every session: the worst it can do is
+ * withhold updates, and then the presets bundled in the npm package are used.
+ *
+ * The signing input is canonical JSON of the six bundle fields that carry
+ * meaning (format, version, min_cli, ratchet_rules, model_rules, agents): keys
+ * sorted recursively, no whitespace. site/assets/preset-sign.js is the browser
+ * copy of canonicalJson(); test/preset-sign.test.js signs with that copy and
+ * verifies with this one, so the two cannot drift apart.
+ *
+ * Verification here is synchronous (node:crypto with IEEE P1363 signatures,
+ * the encoding WebCrypto produces), because the presets are read on the
+ * session-start path by functions that are synchronous today. It takes well
+ * under a millisecond.
+ */
+
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+/**
+ * Public keys allowed to sign preset bundles: [{ kid, jwk }].
+ *
+ * EMPTY until the superuser creates the signing key in the /ops console
+ * (sprag.io/ops/#presets → Signing key → Create). After that, paste the public
+ * JWK shown there as one entry, with `kid` set to the fingerprint the console
+ * shows next to it, e.g.
+ *
+ *   { kid: '0123456789abcdef', jwk: { kty: 'EC', crv: 'P-256', x: '…', y: '…' } }
+ *
+ * While this list is empty every remote bundle is rejected and the bundled
+ * presets are used; `sprag presets status` says so. Rotating the key means
+ * adding the new entry, releasing, then publishing with the new key; remove the
+ * old entry one release later.
+ */
+export const PRESET_SIGNING_KEYS = [];
+
+export const PRESET_BUNDLE_FORMAT = 1;
+export const PRESET_MAX_BYTES = 200 * 1024;
+
+/** JSON with object keys sorted at every depth and no whitespace. */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'number' && !Number.isFinite(value)) return 'null';
+    return value === undefined ? 'null' : JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => (v === undefined || typeof v === 'function' ? 'null' : canonicalJson(v))).join(',') + ']';
+  }
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined && typeof value[k] !== 'function').sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}';
+}
+
+/** The exact bytes that are signed. Fields outside the six are not covered. */
+export function signingInput(bundle) {
+  const b = bundle || {};
+  return canonicalJson({
+    format: b.format ?? null,
+    version: b.version ?? null,
+    min_cli: b.min_cli ?? null,
+    ratchet_rules: b.ratchet_rules ?? null,
+    model_rules: b.model_rules ?? null,
+    agents: b.agents ?? null,
+  });
+}
+
+/** sha256 of the canonical public JWK (kty, crv, x, y only), first 16 hex. */
+export function jwkFingerprint(jwk) {
+  const pub = { crv: jwk?.crv, kty: jwk?.kty, x: jwk?.x, y: jwk?.y };
+  return createHash('sha256').update(canonicalJson(pub)).digest('hex').slice(0, 16);
+}
+
+function b64urlDecode(s) {
+  if (typeof s !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(s)) return null;
+  return Buffer.from(s.replace(/=+$/, '').replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+
+/**
+ * Check a bundle's signature. Returns { ok: true, kid } or
+ * { ok: false, reason } where reason is one of
+ *   'unsigned'     the bundle carries no signature (version 1 is seeded unsigned)
+ *   'no-keys'      this CLI has no signing key yet (PRESET_SIGNING_KEYS is empty)
+ *   'unknown-kid'  signed by a key this CLI does not list
+ *   'bad-sig'      the signature does not match the content
+ */
+export function verifyBundleSignature(bundle, keys = PRESET_SIGNING_KEYS) {
+  const sig = bundle && bundle.sig;
+  if (!sig || typeof sig !== 'object' || !sig.value) return { ok: false, reason: 'unsigned' };
+  if (!Array.isArray(keys) || keys.length === 0) return { ok: false, reason: 'no-keys' };
+  if (sig.alg !== 'ES256') return { ok: false, reason: 'bad-sig' };
+  const entry = keys.find((k) => k && k.kid === sig.kid);
+  if (!entry) return { ok: false, reason: 'unknown-kid' };
+  const raw = b64urlDecode(sig.value);
+  if (!raw || raw.length !== 64) return { ok: false, reason: 'bad-sig' };
+  try {
+    const key = createPublicKey({ key: { kty: 'EC', crv: 'P-256', x: entry.jwk.x, y: entry.jwk.y }, format: 'jwk' });
+    const ok = cryptoVerify('sha256', Buffer.from(signingInput(bundle), 'utf8'), { key, dsaEncoding: 'ieee-p1363' }, raw);
+    return ok ? { ok: true, kid: entry.kid } : { ok: false, reason: 'bad-sig' };
+  } catch {
+    return { ok: false, reason: 'bad-sig' };
+  }
+}

package/src/preset-sync.js

@@ -0,0 +1,133 @@
+/**
+ * preset-sync — fetch the centrally published preset bundle.
+ *
+ * Read-only and anonymous: two RPC calls to the same Supabase project the team
+ * layer uses, with the public anon key and no member key, so the request is all
+ * that leaves the machine. `presets_version()` is polled first because it is a
+ * few bytes; `presets_published()` is fetched only when the version moved.
+ *
+ * Cadence: at most once every 24 hours, from a detached child spawned on the
+ * SessionStart path (the same pattern as the update check and the team sync),
+ * so a session never waits on the network. The attempt is stamped before the
+ * spawn, so an offline machine does not spawn a doomed child every session.
+ *
+ * A fetched bundle is stored only when this CLI would apply it (see
+ * presets-source.js evaluateBundle). A rejected one is recorded with its reason
+ * so `sprag presets status` can say why the bundled presets are still in use.
+ *
+ * Opt out with SPRAG_NO_PRESET_SYNC=1 or SPRAG_NO_UPDATE_CHECK=1.
+ */
+
+import * as childProcess from 'node:child_process';
+import { userDataDir } from './paths.js';
+import { writeStateFile } from './state-file.js';
+import { debug } from './debug.js';
+import {
+  cliVersion, evaluateBundle, presetSyncDisabled, readRemoteCache, remoteCachePath, resetPresetSourceMemo,
+} from './presets-source.js';
+import { PRESET_SIGNING_KEYS } from './preset-sign.js';
+import { CLI_ENTRY, detachedChildEnv, isDetachedChild } from './cli-entry.js';
+
+export const PRESET_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function writeCache(cache, dir) {
+  writeStateFile(remoteCachePath(dir), JSON.stringify(cache, null, 2) + '\n');
+  resetPresetSourceMemo();
+}
+
+/** Due when the last attempt (success or not) is 24 hours old, or there was none. */
+export function presetSyncDue(cache, now = Date.now()) {
+  const at = Number(cache && cache.checkedAt);
+  return !Number.isFinite(at) || at <= 0 || now - at >= PRESET_SYNC_INTERVAL_MS || now < at;
+}
+
+export function nextPresetCheckAt(cache) {
+  const at = Number(cache && cache.checkedAt);
+  return Number.isFinite(at) && at > 0 ? at + PRESET_SYNC_INTERVAL_MS : null;
+}
+
+/**
+ * Called on session start. Never awaits the network. Returns true when a child
+ * was spawned.
+ */
+export function spawnPresetSyncIfDue({
+  env = process.env, now = Date.now(), dir = userDataDir(),
+  spawn = childProcess.spawn, cliPath = CLI_ENTRY, execPath = process.execPath,
+} = {}) {
+  if (isDetachedChild(env) || presetSyncDisabled(env)) return false;
+  const cache = readRemoteCache(dir);
+  if (!presetSyncDue(cache, now)) return false;
+  try {
+    writeCache({ ...cache, checkedAt: now }, dir);
+  } catch (e) {
+    debug('preset-sync:stamp', e);
+    return false;
+  }
+  try {
+    spawn(execPath, [cliPath, 'presets', 'sync', '--background'],
+      { detached: true, stdio: 'ignore', windowsHide: true, env: detachedChildEnv(env) }).unref();
+    return true;
+  } catch (e) {
+    debug('preset-sync:spawn', e);
+    return false;
+  }
+}
+
+/**
+ * Fetch now. Returns { status, version?, reason? } where status is
+ *   'disabled' | 'none' (nothing published) | 'current' (cached version is the
+ *   published one) | 'updated' | 'rejected' | 'error'
+ * `force` refetches the bundle even when the version did not move.
+ */
+export async function syncPresets({
+  env = process.env, now = Date.now(), dir = userDataDir(), fetch, force = false,
+  version = cliVersion(), keys = PRESET_SIGNING_KEYS,
+} = {}) {
+  if (presetSyncDisabled(env)) return { status: 'disabled' };
+  const { rpc, teamApiUrl, teamAnonKey } = await import('./team-sync.js');
+  const call = (fn) => rpc(fn, {}, { fetch, url: teamApiUrl(env), key: teamAnonKey(env) });
+  const cache = readRemoteCache(dir);
+  const base = { ...cache, checkedAt: now };
+  // The cached bundle counts only while it still verifies: after a key rotation
+  // the same version has to be fetched again rather than skipped as current.
+  const cachedOk = cache.bundle && evaluateBundle(cache.bundle, { version, keys }).ok;
+  const have = cachedOk ? cache.bundle.version : 0;
+  try {
+    const head = await call('presets_version');
+    if (!head || !Number.isInteger(head.version)) {
+      writeCache({ ...base, lastError: null }, dir);
+      return { status: 'none' };
+    }
+    if (!force && head.version === have) {
+      writeCache({ ...base, lastError: null }, dir);
+      return { status: 'current', version: have };
+    }
+    if (!force && cache.rejected && cache.rejected.version === head.version && cache.rejected.cli === version
+        && cache.rejected.keys === keys.length) {
+      writeCache({ ...base, lastError: null }, dir);
+      return { status: 'rejected', version: head.version, reason: cache.rejected.reason };
+    }
+    const bundle = await call('presets_published');
+    if (!bundle) {
+      writeCache({ ...base, lastError: null }, dir);
+      return { status: 'none' };
+    }
+    if (Number.isInteger(bundle.version) && bundle.version < have) {
+      const rejected = { version: bundle.version, reason: 'older', at: now, cli: version, keys: keys.length };
+      writeCache({ ...base, rejected, lastError: null }, dir);
+      return { status: 'rejected', version: bundle.version, reason: 'older' };
+    }
+    const ev = evaluateBundle(bundle, { version, keys });
+    if (!ev.ok) {
+      const rejected = { version: Number.isInteger(bundle.version) ? bundle.version : null, reason: ev.reason, at: now, cli: version, keys: keys.length };
+      writeCache({ ...base, rejected, lastError: null }, dir);
+      return { status: 'rejected', version: rejected.version, reason: ev.reason };
+    }
+    writeCache({ checkedAt: now, fetchedAt: now, version: bundle.version, bundle, rejected: null, lastError: null }, dir);
+    return { status: 'updated', version: bundle.version };
+  } catch (e) {
+    debug('preset-sync', e);
+    writeCache({ ...base, lastError: { message: String(e && e.message || e).slice(0, 200), at: now } }, dir);
+    return { status: 'error', reason: String(e && e.message || e) };
+  }
+}