@thejoseki/clawform 2.3.0 → 2.3.2

package/src/lib/providers/polar.js

@@ -1,215 +1,215 @@
-// Polar adapter for the vendor-agnostic license client. Maps the Polar
-// customer-portal license-key API onto {status: valid|invalid|error}.
-//
-// The customer-portal endpoints authenticate with the license key + the
-// organization id alone — there is NO server secret to embed, which is why the
-// adapter can ship in a public tarball. Endpoints and error mapping verified
-// against polarsource/polar (2026-07):
-//   activate/validate/deactivate under /v1/customer-portal/license-keys/
-//   NotPermitted → 403 (limit reached / expired), ResourceNotFound → 404.
-
-const PATH = '/v1/customer-portal/license-keys';
-
-// A 403 body distinguishes "no slots left" from "expired" by its message; both
-// are terminal (status:'invalid') but the reason drives a different hint.
-function classify403(body) {
-  const detail = String(body?.detail ?? '').toLowerCase();
-  if (detail.includes('expired')) return 'expired';
-  if (detail.includes('limit')) return 'limit_reached';
-  return 'not_permitted';
-}
-
-// Polar answers 404 both for a key that does not exist and for a key that
-// belongs to a different product ("License key does not match given benefit.",
-// observed live). Collapsing them tells a buyer with a perfectly valid key to
-// go hunting for typos.
-function classify404(body) {
-  const detail = String(body?.detail ?? '').toLowerCase();
-  if (detail.includes('benefit')) return 'wrong_product';
-  return 'not_found';
-}
-
-export function createPolarClient({
-  fetch: fetchImpl = fetch,
-  baseUrl,
-  organizationId,
-  benefitIds,
-  ...rest
-} = {}) {
-  // `benefitId` (singular) was this option's name until tiers arrived. Left
-  // unhandled it destructures away, leaves the list empty, and yields a client
-  // that enforces nothing — a key from any product in the organization would
-  // then activate. Refuse loudly instead: a crash in the licence path is
-  // fail-closed, and silence here is the failure mode with no symptom.
-  if ('benefitId' in rest) {
-    throw new Error('createPolarClient: `benefitId` was superseded by `benefitIds` (a list, one entry per paid tier).');
-  }
-
-  // One benefit per paid tier: Polar carries limit_activations on the benefit,
-  // so a 3-device seat and a 10-device team seat cannot share one. A key is
-  // accepted when it matches ANY of them.
-  //
-  // A bare string is wrapped rather than ignored. Ignoring it would turn a
-  // config mistake into a client that enforces nothing — silently permissive is
-  // the one failure this whole check exists to prevent.
-  const ids = benefitIds == null ? [] : (Array.isArray(benefitIds) ? benefitIds : [benefitIds]);
-
-  // Which product this key was bought for. Polar nests it differently per
-  // endpoint: activate returns an activation with the licence inside, validate
-  // returns the licence itself. Reading both here keeps the asymmetry in one
-  // place instead of in each caller.
-  const wrongProduct = (body) => {
-    if (!ids.length) return false; // unset: constructor used in isolation
-    const found = body?.benefit_id ?? body?.license_key?.benefit_id;
-    return Boolean(found) && !ids.includes(found);
-  };
-
-  async function post(endpoint, body) {
-    // Any thrown fetch (DNS, connection, timeout), a 5xx, or a 429 is an
-    // OUTAGE or a throttle, not a rejection — it maps to 'error' so the
-    // caller's offline grace applies. Only a deliberate 403/404 from Polar is
-    // 'invalid'.
-    let resp;
-    try {
-      resp = await fetchImpl(`${baseUrl}${PATH}/${endpoint}`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ organization_id: organizationId, ...body }),
-      });
-    } catch (err) {
-      return { kind: 'error', reason: err?.message ?? 'network error' };
-    }
-    if (resp.status >= 500) return { kind: 'error', reason: `HTTP ${resp.status}` };
-    // Throttling, observed against the live API when calls come in a burst.
-    // Named rather than passed through as a status code: the caller's generic
-    // error text tells the user to retry "once you are online", which is
-    // false here and unhelpful to someone whose retries caused it.
-    if (resp.status === 429) return { kind: 'error', reason: 'rate_limited' };
-    let json = {};
-    try { json = await resp.json(); } catch { /* empty body (e.g. 204) is fine */ }
-    return { kind: 'http', status: resp.status, ok: resp.ok, body: json };
-  }
-
-  // Asking the vendor to enforce the product beats comparing its answer.
-  // `benefit_id` is a documented request field and Polar rejects a mismatch
-  // with 404 "License key does not match given benefit." — verified live.
-  // Sent only when configured, so the constructor stays usable in isolation.
-  async function validateOnce(key, activationId, benefitId) {
-    const body = activationId ? { key, activation_id: activationId } : { key };
-    return post('validate', benefitId ? { ...body, benefit_id: benefitId } : body);
-  }
-
-  // A request carries one benefit, so several tiers means several attempts.
-  //
-  // Two stopping rules, both about not lying to the caller:
-  //
-  //   - Anything that is not a flat rejection ends the walk immediately. An
-  //     unreachable vendor must stay 'error', because that is what the 14-day
-  //     offline grace keys off; continuing and reporting whatever the last tier
-  //     said would lock a paying customer out during someone else's outage.
-  //   - A rejection that describes the KEY — it does not exist, it expired, it
-  //     is out of slots — is authoritative whatever tier answered, so it wins
-  //     over a mere "not this benefit". Only 'wrong_product' is worth retrying,
-  //     because only it is a statement about the benefit rather than the key.
-  // A successful walk also reports WHICH benefit answered. That is not
-  // bookkeeping: it is how a caller tells a trial key from a paid one, and
-  // therefore whether the vendor's own delivery service may be consulted at
-  // all. Deriving it a second time at the call site would mean a second copy of
-  // the tier list, which is the drift this whole module exists to prevent.
-  async function validateAcrossBenefits(key, activationId) {
-    if (!ids.length) return fromValidate(await validateOnce(key, activationId, null));
-
-    let last;
-    for (const benefitId of ids) {
-      const res = fromValidate(await validateOnce(key, activationId, benefitId));
-      if (res.status === 'valid') return { ...res, benefitId };
-      if (res.status !== 'invalid') return res;
-      if (res.reason !== 'wrong_product') return res;
-      last = res;
-    }
-    return last;
-  }
-
-  // Observed live: Polar puts `expires_at` on the 200 for a key that is still
-  // valid, so a trial's end date is known at activation rather than discovered
-  // when it lapses. Omitted entirely when the vendor gives none — a perpetual
-  // seat with `expiresAt: undefined` would read as "expired at the epoch" to
-  // anything doing date arithmetic.
-  const expiryOf = (body) => {
-    const at = body?.expires_at ?? body?.license_key?.expires_at;
-    return at ? { expiresAt: at } : {};
-  };
-
-  function fromValidate(r) {
-    if (r.kind === 'error') return { status: 'error', reason: r.reason };
-    if (r.ok) {
-      // Secondary, and fail-open by design: the server is authoritative, and
-      // a response that simply omits the field must not lock a buyer out.
-      if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
-      return { status: 'valid', ...expiryOf(r.body) };
-    }
-    if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
-    if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
-    return { status: 'error', reason: `HTTP ${r.status}` };
-  }
-
-  return {
-    configured: true,
-
-    async activate(key, fingerprint, { validated } = {}) {
-      // Prove the product BEFORE asking Polar to create anything. Checking the
-      // activate response is too late: the activation already exists, and it
-      // spent a slot on the other product's key. The person penalised is that
-      // product's paying customer, for running one wrong command.
-      //
-      // `validated` lets a caller that has ALREADY walked the list hand the
-      // answer over instead of paying for it twice. The CLI's activate has to
-      // validate first anyway — it branches on the matched benefit to decide
-      // whether the trial-claim service is consulted — and the duplication cost
-      // a real activation a 429. Opt-in, never the default: supply nothing and
-      // the pre-check still runs.
-      //
-      // The matched tier is carried through rather than re-derived from the
-      // activate response — the two endpoints nest the field differently, and
-      // one of the two paths is always the one that gets forgotten.
-      let benefitId;
-      let expiry = {};
-      if (ids.length) {
-        const pre = validated ?? await validateAcrossBenefits(key);
-        if (pre.status !== 'valid') return pre;
-        benefitId = pre.benefitId;
-        // The validate response is where the expiry lives; the activate
-        // response describes an activation, not the licence behind it.
-        if (pre.expiresAt) expiry = { expiresAt: pre.expiresAt };
-      }
-
-      const r = await post('activate', { key, label: `clawform ${fingerprint}` });
-      if (r.kind === 'error') return { status: 'error', reason: r.reason };
-      if (r.ok) {
-        if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
-        return {
-          status: 'valid',
-          instanceId: r.body?.id,
-          holder: r.body?.license_key?.customer?.email,
-          ...(benefitId ? { benefitId } : {}),
-          ...expiry,
-          ...expiryOf(r.body),
-        };
-      }
-      if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
-      if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
-      return { status: 'error', reason: `HTTP ${r.status}` };
-    },
-
-    async validate(key, activationId) {
-      return validateAcrossBenefits(key, activationId);
-    },
-
-    async deactivate(key, activationId) {
-      const r = await post('deactivate', { key, activation_id: activationId });
-      if (r.kind === 'error') return { status: 'error', reason: r.reason };
-      if (r.ok) return { status: 'valid' };
-      return { status: 'error', reason: `HTTP ${r.status}` };
-    },
-  };
-}
+// Polar adapter for the vendor-agnostic license client. Maps the Polar
+// customer-portal license-key API onto {status: valid|invalid|error}.
+//
+// The customer-portal endpoints authenticate with the license key + the
+// organization id alone — there is NO server secret to embed, which is why the
+// adapter can ship in a public tarball. Endpoints and error mapping verified
+// against polarsource/polar (2026-07):
+//   activate/validate/deactivate under /v1/customer-portal/license-keys/
+//   NotPermitted → 403 (limit reached / expired), ResourceNotFound → 404.
+
+const PATH = '/v1/customer-portal/license-keys';
+
+// A 403 body distinguishes "no slots left" from "expired" by its message; both
+// are terminal (status:'invalid') but the reason drives a different hint.
+function classify403(body) {
+  const detail = String(body?.detail ?? '').toLowerCase();
+  if (detail.includes('expired')) return 'expired';
+  if (detail.includes('limit')) return 'limit_reached';
+  return 'not_permitted';
+}
+
+// Polar answers 404 both for a key that does not exist and for a key that
+// belongs to a different product ("License key does not match given benefit.",
+// observed live). Collapsing them tells a buyer with a perfectly valid key to
+// go hunting for typos.
+function classify404(body) {
+  const detail = String(body?.detail ?? '').toLowerCase();
+  if (detail.includes('benefit')) return 'wrong_product';
+  return 'not_found';
+}
+
+export function createPolarClient({
+  fetch: fetchImpl = fetch,
+  baseUrl,
+  organizationId,
+  benefitIds,
+  ...rest
+} = {}) {
+  // `benefitId` (singular) was this option's name until tiers arrived. Left
+  // unhandled it destructures away, leaves the list empty, and yields a client
+  // that enforces nothing — a key from any product in the organization would
+  // then activate. Refuse loudly instead: a crash in the licence path is
+  // fail-closed, and silence here is the failure mode with no symptom.
+  if ('benefitId' in rest) {
+    throw new Error('createPolarClient: `benefitId` was superseded by `benefitIds` (a list, one entry per paid tier).');
+  }
+
+  // One benefit per paid tier: Polar carries limit_activations on the benefit,
+  // so a 3-device seat and a 10-device team seat cannot share one. A key is
+  // accepted when it matches ANY of them.
+  //
+  // A bare string is wrapped rather than ignored. Ignoring it would turn a
+  // config mistake into a client that enforces nothing — silently permissive is
+  // the one failure this whole check exists to prevent.
+  const ids = benefitIds == null ? [] : (Array.isArray(benefitIds) ? benefitIds : [benefitIds]);
+
+  // Which product this key was bought for. Polar nests it differently per
+  // endpoint: activate returns an activation with the licence inside, validate
+  // returns the licence itself. Reading both here keeps the asymmetry in one
+  // place instead of in each caller.
+  const wrongProduct = (body) => {
+    if (!ids.length) return false; // unset: constructor used in isolation
+    const found = body?.benefit_id ?? body?.license_key?.benefit_id;
+    return Boolean(found) && !ids.includes(found);
+  };
+
+  async function post(endpoint, body) {
+    // Any thrown fetch (DNS, connection, timeout), a 5xx, or a 429 is an
+    // OUTAGE or a throttle, not a rejection — it maps to 'error' so the
+    // caller's offline grace applies. Only a deliberate 403/404 from Polar is
+    // 'invalid'.
+    let resp;
+    try {
+      resp = await fetchImpl(`${baseUrl}${PATH}/${endpoint}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ organization_id: organizationId, ...body }),
+      });
+    } catch (err) {
+      return { kind: 'error', reason: err?.message ?? 'network error' };
+    }
+    if (resp.status >= 500) return { kind: 'error', reason: `HTTP ${resp.status}` };
+    // Throttling, observed against the live API when calls come in a burst.
+    // Named rather than passed through as a status code: the caller's generic
+    // error text tells the user to retry "once you are online", which is
+    // false here and unhelpful to someone whose retries caused it.
+    if (resp.status === 429) return { kind: 'error', reason: 'rate_limited' };
+    let json = {};
+    try { json = await resp.json(); } catch { /* empty body (e.g. 204) is fine */ }
+    return { kind: 'http', status: resp.status, ok: resp.ok, body: json };
+  }
+
+  // Asking the vendor to enforce the product beats comparing its answer.
+  // `benefit_id` is a documented request field and Polar rejects a mismatch
+  // with 404 "License key does not match given benefit." — verified live.
+  // Sent only when configured, so the constructor stays usable in isolation.
+  async function validateOnce(key, activationId, benefitId) {
+    const body = activationId ? { key, activation_id: activationId } : { key };
+    return post('validate', benefitId ? { ...body, benefit_id: benefitId } : body);
+  }
+
+  // A request carries one benefit, so several tiers means several attempts.
+  //
+  // Two stopping rules, both about not lying to the caller:
+  //
+  //   - Anything that is not a flat rejection ends the walk immediately. An
+  //     unreachable vendor must stay 'error', because that is what the 14-day
+  //     offline grace keys off; continuing and reporting whatever the last tier
+  //     said would lock a paying customer out during someone else's outage.
+  //   - A rejection that describes the KEY — it does not exist, it expired, it
+  //     is out of slots — is authoritative whatever tier answered, so it wins
+  //     over a mere "not this benefit". Only 'wrong_product' is worth retrying,
+  //     because only it is a statement about the benefit rather than the key.
+  // A successful walk also reports WHICH benefit answered. That is not
+  // bookkeeping: it is how a caller tells a trial key from a paid one, and
+  // therefore whether the vendor's own delivery service may be consulted at
+  // all. Deriving it a second time at the call site would mean a second copy of
+  // the tier list, which is the drift this whole module exists to prevent.
+  async function validateAcrossBenefits(key, activationId) {
+    if (!ids.length) return fromValidate(await validateOnce(key, activationId, null));
+
+    let last;
+    for (const benefitId of ids) {
+      const res = fromValidate(await validateOnce(key, activationId, benefitId));
+      if (res.status === 'valid') return { ...res, benefitId };
+      if (res.status !== 'invalid') return res;
+      if (res.reason !== 'wrong_product') return res;
+      last = res;
+    }
+    return last;
+  }
+
+  // Observed live: Polar puts `expires_at` on the 200 for a key that is still
+  // valid, so a trial's end date is known at activation rather than discovered
+  // when it lapses. Omitted entirely when the vendor gives none — a perpetual
+  // seat with `expiresAt: undefined` would read as "expired at the epoch" to
+  // anything doing date arithmetic.
+  const expiryOf = (body) => {
+    const at = body?.expires_at ?? body?.license_key?.expires_at;
+    return at ? { expiresAt: at } : {};
+  };
+
+  function fromValidate(r) {
+    if (r.kind === 'error') return { status: 'error', reason: r.reason };
+    if (r.ok) {
+      // Secondary, and fail-open by design: the server is authoritative, and
+      // a response that simply omits the field must not lock a buyer out.
+      if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
+      return { status: 'valid', ...expiryOf(r.body) };
+    }
+    if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
+    if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
+    return { status: 'error', reason: `HTTP ${r.status}` };
+  }
+
+  return {
+    configured: true,
+
+    async activate(key, fingerprint, { validated } = {}) {
+      // Prove the product BEFORE asking Polar to create anything. Checking the
+      // activate response is too late: the activation already exists, and it
+      // spent a slot on the other product's key. The person penalised is that
+      // product's paying customer, for running one wrong command.
+      //
+      // `validated` lets a caller that has ALREADY walked the list hand the
+      // answer over instead of paying for it twice. The CLI's activate has to
+      // validate first anyway — it branches on the matched benefit to decide
+      // whether the trial-claim service is consulted — and the duplication cost
+      // a real activation a 429. Opt-in, never the default: supply nothing and
+      // the pre-check still runs.
+      //
+      // The matched tier is carried through rather than re-derived from the
+      // activate response — the two endpoints nest the field differently, and
+      // one of the two paths is always the one that gets forgotten.
+      let benefitId;
+      let expiry = {};
+      if (ids.length) {
+        const pre = validated ?? await validateAcrossBenefits(key);
+        if (pre.status !== 'valid') return pre;
+        benefitId = pre.benefitId;
+        // The validate response is where the expiry lives; the activate
+        // response describes an activation, not the licence behind it.
+        if (pre.expiresAt) expiry = { expiresAt: pre.expiresAt };
+      }
+
+      const r = await post('activate', { key, label: `clawform ${fingerprint}` });
+      if (r.kind === 'error') return { status: 'error', reason: r.reason };
+      if (r.ok) {
+        if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
+        return {
+          status: 'valid',
+          instanceId: r.body?.id,
+          holder: r.body?.license_key?.customer?.email,
+          ...(benefitId ? { benefitId } : {}),
+          ...expiry,
+          ...expiryOf(r.body),
+        };
+      }
+      if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
+      if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
+      return { status: 'error', reason: `HTTP ${r.status}` };
+    },
+
+    async validate(key, activationId) {
+      return validateAcrossBenefits(key, activationId);
+    },
+
+    async deactivate(key, activationId) {
+      const r = await post('deactivate', { key, activation_id: activationId });
+      if (r.kind === 'error') return { status: 'error', reason: r.reason };
+      if (r.ok) return { status: 'valid' };
+      return { status: 'error', reason: `HTTP ${r.status}` };
+    },
+  };
+}

package/src/lib/session-state.js

@@ -1,91 +1,91 @@
-// In-flight deploy state — survives `/clear` and new sessions.
-//
-// What clawform persists is NOT conversation (that's the consumer's kit's job) —
-// it's the AWS operation left mid-flight: a changeset created but not yet
-// executed. `clawform deploy` records it here right after CreateChangeSet and
-// clears it after ExecuteChangeSet; if the operator aborts at the confirm
-// prompt (or runs `/clear`), the entry survives so the SessionStart context
-// hook can warn the next session that a changeset is sitting unexecuted.
-//
-// State file: <projectDir>/.clawform-state.json (gitignored). Stores only
-// stack name + changeset name + env + createdAt — never account IDs, ARNs,
-// or template bodies. All reads fail-open: a missing or corrupt file yields
-// an empty state, never an exception, so a bad state file never blocks a
-// deploy or a session start.
-
-import { readFileSync as fsReadFileSync, writeFileSync as fsWriteFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-export const STATE_FILENAME = '.clawform-state.json';
-export const STATE_VERSION = 1;
-export const STALE_CHANGESET_DAYS = 7;
-
-function statePath(projectDir) {
-  return join(projectDir, STATE_FILENAME);
-}
-
-function emptyState() {
-  return { v: STATE_VERSION, pendingChangesets: [] };
-}
-
-export function readState(projectDir, { readFileSync = fsReadFileSync } = {}) {
-  let raw;
-  try {
-    raw = readFileSync(statePath(projectDir), 'utf8');
-  } catch {
-    return emptyState();
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || parsed.v !== STATE_VERSION || !Array.isArray(parsed.pendingChangesets)) {
-      return emptyState();
-    }
-    return parsed;
-  } catch {
-    return emptyState();
-  }
-}
-
-export function writeState(projectDir, state, { writeFileSync = fsWriteFileSync } = {}) {
-  writeFileSync(statePath(projectDir), JSON.stringify(state, null, 2));
-}
-
-const changesetKey = (e) => `${e.stack} ${e.changeSetName}`;
-
-const DAY_MS = 86_400_000;
-
-// Entries older than the stale threshold are treated as abandoned — a
-// changeset the operator never executed and never will. We can't clear those
-// on the read path (the SessionStart hook must not write), so we self-heal on
-// the write path: every `addPendingChangeset` (i.e. every new deploy) drops any
-// entry past the threshold. This bounds accumulation and means a phantom entry
-// disappears on the next deploy without the operator hand-editing the file.
-function isStale(entry, now) {
-  const created = Date.parse(entry?.createdAt);
-  if (!Number.isFinite(created)) return true; // unparseable createdAt → treat as junk, prune
-  return now - created > STALE_CHANGESET_DAYS * DAY_MS;
-}
-
-// Record (or refresh) a pending changeset. Stores only the safe fields; a
-// repeated stack+changeset replaces the prior entry (latest createdAt wins).
-// Prunes stale/abandoned entries in the same write (self-healing).
-export function addPendingChangeset(projectDir, entry, deps = {}) {
-  const now = typeof deps.now === 'number' ? deps.now : Date.now();
-  const state = readState(projectDir, deps);
-  const next = state.pendingChangesets
-    .filter((e) => changesetKey(e) !== changesetKey(entry))
-    .filter((e) => !isStale(e, now));
-  next.push({
-    stack: entry.stack,
-    changeSetName: entry.changeSetName,
-    env: entry.env,
-    createdAt: entry.createdAt,
-  });
-  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
-}
-
-export function clearPendingChangeset(projectDir, { stack, changeSetName }, deps = {}) {
-  const state = readState(projectDir, deps);
-  const next = state.pendingChangesets.filter((e) => !(e.stack === stack && e.changeSetName === changeSetName));
-  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
-}
+// In-flight deploy state — survives `/clear` and new sessions.
+//
+// What clawform persists is NOT conversation (that's the consumer's kit's job) —
+// it's the AWS operation left mid-flight: a changeset created but not yet
+// executed. `clawform deploy` records it here right after CreateChangeSet and
+// clears it after ExecuteChangeSet; if the operator aborts at the confirm
+// prompt (or runs `/clear`), the entry survives so the SessionStart context
+// hook can warn the next session that a changeset is sitting unexecuted.
+//
+// State file: <projectDir>/.clawform-state.json (gitignored). Stores only
+// stack name + changeset name + env + createdAt — never account IDs, ARNs,
+// or template bodies. All reads fail-open: a missing or corrupt file yields
+// an empty state, never an exception, so a bad state file never blocks a
+// deploy or a session start.
+
+import { readFileSync as fsReadFileSync, writeFileSync as fsWriteFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const STATE_FILENAME = '.clawform-state.json';
+export const STATE_VERSION = 1;
+export const STALE_CHANGESET_DAYS = 7;
+
+function statePath(projectDir) {
+  return join(projectDir, STATE_FILENAME);
+}
+
+function emptyState() {
+  return { v: STATE_VERSION, pendingChangesets: [] };
+}
+
+export function readState(projectDir, { readFileSync = fsReadFileSync } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(statePath(projectDir), 'utf8');
+  } catch {
+    return emptyState();
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.v !== STATE_VERSION || !Array.isArray(parsed.pendingChangesets)) {
+      return emptyState();
+    }
+    return parsed;
+  } catch {
+    return emptyState();
+  }
+}
+
+export function writeState(projectDir, state, { writeFileSync = fsWriteFileSync } = {}) {
+  writeFileSync(statePath(projectDir), JSON.stringify(state, null, 2));
+}
+
+const changesetKey = (e) => `${e.stack} ${e.changeSetName}`;
+
+const DAY_MS = 86_400_000;
+
+// Entries older than the stale threshold are treated as abandoned — a
+// changeset the operator never executed and never will. We can't clear those
+// on the read path (the SessionStart hook must not write), so we self-heal on
+// the write path: every `addPendingChangeset` (i.e. every new deploy) drops any
+// entry past the threshold. This bounds accumulation and means a phantom entry
+// disappears on the next deploy without the operator hand-editing the file.
+function isStale(entry, now) {
+  const created = Date.parse(entry?.createdAt);
+  if (!Number.isFinite(created)) return true; // unparseable createdAt → treat as junk, prune
+  return now - created > STALE_CHANGESET_DAYS * DAY_MS;
+}
+
+// Record (or refresh) a pending changeset. Stores only the safe fields; a
+// repeated stack+changeset replaces the prior entry (latest createdAt wins).
+// Prunes stale/abandoned entries in the same write (self-healing).
+export function addPendingChangeset(projectDir, entry, deps = {}) {
+  const now = typeof deps.now === 'number' ? deps.now : Date.now();
+  const state = readState(projectDir, deps);
+  const next = state.pendingChangesets
+    .filter((e) => changesetKey(e) !== changesetKey(entry))
+    .filter((e) => !isStale(e, now));
+  next.push({
+    stack: entry.stack,
+    changeSetName: entry.changeSetName,
+    env: entry.env,
+    createdAt: entry.createdAt,
+  });
+  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
+}
+
+export function clearPendingChangeset(projectDir, { stack, changeSetName }, deps = {}) {
+  const state = readState(projectDir, deps);
+  const next = state.pendingChangesets.filter((e) => !(e.stack === stack && e.changeSetName === changeSetName));
+  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
+}