thumbgate 1.27.20 → 1.28.0

package/scripts/entitlement.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * entitlement.js — signed license entitlements for ThumbGate's paid tier.
+ *
+ * Replaces the old bypassable `tg_`/`tg_pro_` prefix check in license.js with a
+ * cryptographically-verifiable, offline-checkable license token.
+ *
+ * Token format (compact JWS-like, Ed25519 / "EdDSA"):
+ *     base64url(header) "." base64url(payload) "." base64url(signature)
+ *   header  = { alg: "EdDSA", kid }          // kid selects the public key
+ *   payload = { tier, features[], exp, iat, customerId, keyId }
+ *   sig     = Ed25519 over `${b64url(header)}.${b64url(payload)}`
+ *
+ * The PRIVATE signing key lives only in the hosted billing service (or a local
+ * gitignored dev path). Only PUBLIC keys ship, in config/entitlement-public-keys.json,
+ * so any client can verify a license offline without contacting a server.
+ *
+ * Enforcement is opt-in via THUMBGATE_ENFORCE_ENTITLEMENTS so paid features can be
+ * gated without breaking existing users during rollout:
+ *   - advisory (default): requireEntitlement returns {entitled:false, reason} and
+ *     the caller may warn but proceed.
+ *   - enforced (flag set): requireEntitlement throws EntitlementError when not entitled.
+ *
+ * LIMITATION — read before overselling this. This gate runs CLIENT-SIDE in an
+ * MIT, open-source, un-compiled package. It makes a license UN-FORGEABLE (you
+ * cannot mint a valid token without the private key), but it does NOT make the
+ * check UN-BYPASSABLE: anyone with the source can monkey-patch requireEntitlement
+ * or delete the gate. So this protects against fake keys and honest free-riding,
+ * and it is the correct authorization primitive for the HOSTED service — but the
+ * only real, un-bypassable protection for the crown-jewel intelligence is to run
+ * it SERVER-SIDE (client sends inputs, gets outputs, never sees the code/weights),
+ * with these tokens as the auth. Client-side gating is a speed bump, not a wall.
+ * See docs/COMMERCIALIZATION_STRATEGY.md.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const TIER_FEATURES = {
+  free: [],
+  pro: ['recall', 'lesson-search', 'unlimited-rules', 'data-export', 'hosted-dashboard', 'hosted-sync', 'learned-models'],
+  team: ['recall', 'lesson-search', 'unlimited-rules', 'data-export', 'hosted-dashboard', 'hosted-sync', 'learned-models', 'org-visibility'],
+  enterprise: ['recall', 'lesson-search', 'unlimited-rules', 'data-export', 'hosted-dashboard', 'hosted-sync', 'learned-models', 'org-visibility', 'sso', 'audit-log', 'compliance-export'],
+};
+
+class EntitlementError extends Error {
+  constructor(message, code = 'entitlement_denied') {
+    super(message);
+    this.name = 'EntitlementError';
+    this.code = code;
+  }
+}
+
+const advisoryWarnings = new Set();
+
+function b64urlEncode(buf) {
+  return Buffer.from(buf).toString('base64url');
+}
+function b64urlDecodeJson(str) {
+  return JSON.parse(Buffer.from(str, 'base64url').toString('utf8'));
+}
+
+function isTrueEnv(value) {
+  if (!value) return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+function isEnforced(env = process.env) {
+  return isTrueEnv(env.THUMBGATE_ENFORCE_ENTITLEMENTS);
+}
+
+/** Load the shipped public keyset ({ activeKid, keys: {kid: pem} }). */
+function loadTrustedKeys(root = path.resolve(__dirname, '..')) {
+  try {
+    const p = path.join(root, 'config', 'entitlement-public-keys.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return raw.keys || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Verify a license token offline. Returns a normalized result — never throws on
+ * bad input (returns { valid:false, reason }).
+ * @param {string} token
+ * @param {{ trustedKeys?: Record<string,string>, now?: number }} [opts]
+ */
+function verifyLicense(token, opts = {}) {
+  const trustedKeys = opts.trustedKeys || loadTrustedKeys();
+  const now = opts.now || Math.floor(nowMs() / 1000);
+  if (typeof token !== 'string' || !token.trim()) {
+    return { valid: false, reason: 'missing_token' };
+  }
+  // Reject the legacy bypassable prefix keys outright.
+  if (/^tg_/.test(token.trim())) {
+    return { valid: false, reason: 'legacy_prefix_key_not_a_signed_license' };
+  }
+  const parts = token.trim().split('.');
+  if (parts.length !== 3) return { valid: false, reason: 'malformed_token' };
+  const [h, p, s] = parts;
+  let header;
+  let payload;
+  try {
+    header = b64urlDecodeJson(h);
+    payload = b64urlDecodeJson(p);
+  } catch {
+    return { valid: false, reason: 'undecodable_token' };
+  }
+  if (header.alg !== 'EdDSA' || !header.kid) return { valid: false, reason: 'bad_header' };
+  const pubPem = trustedKeys[header.kid];
+  if (!pubPem) return { valid: false, reason: 'unknown_key_id' };
+
+  let signatureOk = false;
+  try {
+    signatureOk = crypto.verify(
+      null,
+      Buffer.from(`${h}.${p}`),
+      crypto.createPublicKey(pubPem),
+      Buffer.from(s, 'base64url')
+    );
+  } catch {
+    return { valid: false, reason: 'signature_verify_error' };
+  }
+  if (!signatureOk) return { valid: false, reason: 'bad_signature' };
+
+  if (typeof payload.exp === 'number' && payload.exp < now) {
+    return { valid: false, reason: 'expired', tier: payload.tier };
+  }
+  const tier = payload.tier || 'free';
+  const features = Array.isArray(payload.features) && payload.features.length
+    ? payload.features
+    : (TIER_FEATURES[tier] || []);
+  return {
+    valid: true,
+    tier,
+    features,
+    customerId: payload.customerId || null,
+    keyId: header.kid,
+    exp: payload.exp || null,
+  };
+}
+
+/**
+ * Sign a license token. PRIVATE-key operation — runs in the hosted billing
+ * service (or a local dev/setup script), never in the shipped client at runtime.
+ * @param {string} privateKeyPem
+ * @param {{ tier:string, features?:string[], customerId?:string, kid:string, expSeconds?:number, iat?:number, exp?:number }} claims
+ */
+function issueLicense(privateKeyPem, claims) {
+  const header = { alg: 'EdDSA', kid: claims.kid };
+  const iat = claims.iat || Math.floor(nowMs() / 1000);
+  const exp = claims.exp || (claims.expSeconds ? iat + claims.expSeconds : undefined);
+  const payload = {
+    tier: claims.tier,
+    features: claims.features || TIER_FEATURES[claims.tier] || [],
+    customerId: claims.customerId || null,
+    keyId: claims.kid,
+    iat,
+    ...(exp ? { exp } : {}),
+  };
+  const h = b64urlEncode(JSON.stringify(header));
+  const p = b64urlEncode(JSON.stringify(payload));
+  const sig = crypto.sign(null, Buffer.from(`${h}.${p}`), crypto.createPrivateKey(privateKeyPem));
+  return `${h}.${p}.${b64urlEncode(sig)}`;
+}
+
+/** Resolve the active license token from env or the local config file. */
+function resolveLicenseToken(env = process.env) {
+  if (env.THUMBGATE_LICENSE && env.THUMBGATE_LICENSE.trim()) return env.THUMBGATE_LICENSE.trim();
+  try {
+    const p = path.join(os.homedir(), '.config', 'thumbgate', 'license.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (raw.license || raw.token) return String(raw.license || raw.token).trim();
+  } catch { /* no local license */ }
+  return null;
+}
+
+/**
+ * Gate a paid feature. Advisory by default; throws EntitlementError only when
+ * THUMBGATE_ENFORCE_ENTITLEMENTS is set. Returns { entitled, tier, reason }.
+ * @param {string} feature
+ * @param {{ env?: NodeJS.ProcessEnv, trustedKeys?: object, token?: string }} [opts]
+ */
+function requireEntitlement(feature, opts = {}) {
+  const env = opts.env || process.env;
+  const token = opts.token !== undefined ? opts.token : resolveLicenseToken(env);
+  const result = verifyLicense(token, { trustedKeys: opts.trustedKeys });
+  const entitled = result.valid && result.features.includes(feature);
+  const decision = {
+    entitled,
+    tier: result.valid ? result.tier : 'free',
+    feature,
+    reason: entitled ? 'entitled' : (result.valid ? 'feature_not_in_tier' : result.reason),
+    enforced: isEnforced(env),
+  };
+  if (!entitled && decision.enforced) {
+    throw new EntitlementError(
+      `ThumbGate: "${feature}" requires a paid license (current tier: ${decision.tier}, reason: ${decision.reason}). `
+      + `Get a license at https://thumbgate.ai/pricing, then set THUMBGATE_LICENSE or ~/.config/thumbgate/license.json.`,
+      decision.reason
+    );
+  }
+  return decision;
+}
+
+/**
+ * Shared paid-feature wrapper for commercial entrypoints. In advisory mode it
+ * emits one warning per feature/label and lets the caller continue; in enforced
+ * mode `requireEntitlement()` throws before this function returns.
+ */
+function requirePaidFeature(feature, opts = {}) {
+  const decision = requireEntitlement(feature, opts);
+  const label = opts.label || feature;
+  const warningKey = `${feature}:${label}`;
+  if (!decision.entitled && !opts.silent && !advisoryWarnings.has(warningKey)) {
+    advisoryWarnings.add(warningKey);
+    console.error(`⚠️ ThumbGate: ${label} requires a paid license (tier: ${decision.tier}). Advisory mode — set THUMBGATE_ENFORCE_ENTITLEMENTS=1 to enforce. License: https://thumbgate.ai/pricing`);
+  }
+  return decision;
+}
+
+function requireLearnedModelsEntitlement(opts = {}) {
+  return requirePaidFeature('learned-models', {
+    ...opts,
+    label: opts.label || 'learned-models intelligence',
+  });
+}
+
+// Injectable clock (Date.now is fine at runtime; kept in one place for testability).
+function nowMs() {
+  return Date.now();
+}
+
+module.exports = {
+  verifyLicense,
+  issueLicense,
+  requireEntitlement,
+  requirePaidFeature,
+  requireLearnedModelsEntitlement,
+  resolveLicenseToken,
+  loadTrustedKeys,
+  isEnforced,
+  TIER_FEATURES,
+  EntitlementError,
+};

package/scripts/export-databricks-bundle.js

@@ -129,6 +129,11 @@ function timestampSlug() {
 }
 
 function exportDatabricksBundle(feedbackDir = getDefaultFeedbackDir(), outputPath, options = {}) {
+  // Paid-feature gate (advisory by default; enforced via THUMBGATE_ENFORCE_ENTITLEMENTS=1).
+  const _ent = require('./entitlement').requireEntitlement('data-export');
+  if (!_ent.entitled) {
+    console.error(`⚠️ ThumbGate: Databricks bundle export is a paid feature (tier: ${_ent.tier}). Advisory mode — set THUMBGATE_ENFORCE_ENTITLEMENTS=1 to enforce. License: https://thumbgate.ai/pricing`);
+  }
   const resolvedFeedbackDir = path.resolve(feedbackDir || getDefaultFeedbackDir());
   const resolvedProofDir = path.resolve(options.proofDir || DEFAULT_PROOF_DIR);
   const exportedAt = new Date().toISOString();

package/scripts/export-dpo-pairs.js

@@ -180,6 +180,12 @@ function toJSONL(pairs) {
 }
 
 function exportDpoFromMemories(memories) {
+  // Paid-feature gate: DPO export is a commercial (Pro+) capability. Advisory by
+  // default; enforced when THUMBGATE_ENFORCE_ENTITLEMENTS=1 (then this throws).
+  const _ent = require('./entitlement').requireEntitlement('data-export');
+  if (!_ent.entitled) {
+    console.error(`⚠️ ThumbGate: DPO export is a paid feature (tier: ${_ent.tier}). Advisory mode — set THUMBGATE_ENFORCE_ENTITLEMENTS=1 to enforce. License: https://thumbgate.ai/pricing`);
+  }
   const errors = memories.filter((m) => m.category === 'error');
   const learnings = memories.filter((m) => m.category === 'learning');
   const result = buildDpoPairs(errors, learnings);

package/scripts/export-hf-dataset.js

@@ -177,6 +177,11 @@ function buildDatasetInfo({ traceCount, preferenceCount, exportedAt }) {
  * @returns {Object} Export summary
  */
 function exportHfDataset(options = {}) {
+  // Paid-feature gate (advisory by default; enforced via THUMBGATE_ENFORCE_ENTITLEMENTS=1).
+  const _ent = require('./entitlement').requireEntitlement('data-export');
+  if (!_ent.entitled) {
+    console.error(`⚠️ ThumbGate: HuggingFace dataset export is a paid feature (tier: ${_ent.tier}). Advisory mode — set THUMBGATE_ENFORCE_ENTITLEMENTS=1 to enforce. License: https://thumbgate.ai/pricing`);
+  }
   const feedbackDir = options.feedbackDir || resolveFeedbackDir();
   const outputDir = options.outputDir || path.join(feedbackDir, 'hf-dataset');
   const includeProvenance = options.includeProvenance !== false;

package/scripts/gates-engine.js

@@ -151,10 +151,22 @@ const DESTRUCTIVE_OR_PRIVILEGE_BOUNDARY_PATTERN = /\b(?:rm\s+-rf|chmod\s+(?:\+x|
 // far better than any single regex). Secret exfiltration and the security-vulnerability
 // scan hard-deny on their OWN paths before this runs, so irreversible data-leak / supply
 // chain risks stay blocked regardless of posture.
+// Self-protective gates guard ThumbGate's own guardrails (kill/env/config/hooks). See the
+// self-protect-binds-regardless-of-posture changeset for the full rationale.
+function isSelfProtectGate(gateId) {
+  return typeof gateId === 'string' && gateId.startsWith('self-protect');
+}
+
 function applyEnforcementPosture(result) {
   if (!result || (result.decision !== 'deny' && result.decision !== 'approve')) return result;
   // Full hard enforcement opt-in: keep every deny.
   if (process.env.THUMBGATE_STRICT_ENFORCEMENT === '1') return result;
+  // Self-protection binds regardless of posture: a warning is worthless once the guardrail is
+  // gone. Owner escape: THUMBGATE_SELF_PROTECT_OVERRIDE=1 (break-glass covers .claude/settings*
+  // but not this surface, so it needs its own escape — self-lockout, 2026-07-07).
+  if (isSelfProtectGate(result.gate) && process.env.THUMBGATE_SELF_PROTECT_OVERRIDE !== '1') {
+    return result;
+  }
   // Honor the explicit strict-knowledge-conflict opt-in for that gate.
   if (process.env.THUMBGATE_STRICT_KNOWLEDGE_CONFLICT === '1' && result.gate === 'knowledge-conflict-gate') return result;
   // Warn-by-default: the gate still fired and is recorded; the action is allowed through
@@ -2672,12 +2684,12 @@ function buildBlockActionProCta() {
     if (totalBlocks < 5) return null; // Too early — let them experience the product
 
     if (totalBlocks < 25) {
-      return '\n\n💡 Pro: keep this rule synced across laptops, CI, containers, and agent runtimes → thumbgate.ai/go/pro';
+      return '\n\n💡 Pro: keep this rule searchable, exportable, and visible → thumbgate.ai/go/pro';
     }
     if (totalBlocks < 100) {
-      return `\n\n💡 ${totalBlocks} actions blocked. Pro keeps these lessons/rules synced everywhere → thumbgate.ai/go/pro ($19/mo)`;
+      return `\n\n💡 ${totalBlocks} actions blocked. Pro adds recall, dashboard proof, and exports → thumbgate.ai/go/pro ($19/mo)`;
     }
-    return `\n\n💡 ${totalBlocks} mistakes caught. Your team could use shared hosted enforcement → thumbgate.ai/go/pro`;
+    return `\n\n💡 ${totalBlocks} mistakes caught. Your team could use Enterprise shared hosted enforcement → thumbgate.ai/go/pro`;
   } catch (_) {
     return null;
   }

package/scripts/imperative-detector.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * imperative-detector.js — detect an explicit NEVER / ALWAYS directive in a
+ * feedback message so the CLI can OFFER immediate enforcement (force-gate) when
+ * the user clearly asked for it.
+ *
+ * Why this exists: auto-promotion is deliberately occurrence-gated (a rule
+ * blocks only after a pattern repeats) — that accumulate-evidence-before-you-
+ * enforce default is what makes ThumbGate trustworthy rather than a one-signal
+ * lockout. But when a user types "never do X again", that is an explicit intent
+ * to guard NOW. This module recognizes that intent and lets the CLI SURFACE the
+ * one-shot path (force-gate) as an offer. It never blocks on its own — the user
+ * still confirms. Detecting intent ≠ acting on it.
+ *
+ * Pure and deterministic: no state, no I/O.
+ */
+
+// A leading (or clause-initial) negative imperative → intent to forbid.
+const NEVER_RE = /(?:^|[.;:,]\s*)(never|do\s*not|don'?t|stop\s+\w|must\s*not|no\s+longer|quit\s+\w|avoid\s+\w)/i;
+// A leading (or clause-initial) positive imperative → intent to always do.
+const ALWAYS_RE = /(?:^|[.;:,]\s*)(always|make\s+sure|ensure\s+\w|be\s+sure\s+to)/i;
+
+function firstMeaningfulText(text) {
+  // Strip common feedback prefixes/quote marks so "❯ never …" still matches.
+  return String(text || '').trim().replace(/^[\s>❯"'`*-]+/, '');
+}
+
+/**
+ * @param {string} text
+ * @returns {{isImperative:boolean, polarity:('never'|'always'|null), directive:string}}
+ */
+function detectImperative(text) {
+  const t = firstMeaningfulText(text);
+  if (!t) return { isImperative: false, polarity: null, directive: '' };
+  // Negative wins if both appear — a forbid directive is the actionable one.
+  if (NEVER_RE.test(t)) return { isImperative: true, polarity: 'never', directive: t };
+  if (ALWAYS_RE.test(t)) return { isImperative: true, polarity: 'always', directive: t };
+  return { isImperative: false, polarity: null, directive: '' };
+}
+
+function shellQuote(text) {
+  return String(text).trim().slice(0, 140).replace(/"/g, "'").replace(/\s+/g, ' ');
+}
+
+/**
+ * Build a suggestion for the capture confirmation. Returns null when there's no
+ * explicit directive to act on.
+ * - down + "never …"  → OFFER immediate force-gate (the user asked to forbid it).
+ * - up   + "always …" → clarify it's stored as guidance, not a hard block.
+ * @param {{signal?:string, text?:string}} opts
+ * @returns {{kind:string, message:string}|null}
+ */
+function suggestForceGate({ signal, text } = {}) {
+  const isDown = signal === 'down' || signal === 'negative' || signal === 'thumbs_down';
+  const det = detectImperative(text);
+  if (!det.isImperative) return null;
+
+  if (isDown && det.polarity === 'never') {
+    const ctx = shellQuote(text);
+    return {
+      kind: 'force-gate-offer',
+      message: 'You said "never" — block this immediately instead of waiting for it to recur:\n'
+        + `    npx thumbgate force-gate --context="${ctx}" --action=block\n`
+        + '  (or run /thumbgate-guard). Left alone, it auto-promotes to a gate after the pattern repeats.',
+    };
+  }
+
+  if (!isDown && det.polarity === 'always') {
+    return {
+      kind: 'always-note',
+      message: 'You said "always" — stored as an ALWAYS guidance principle. '
+        + 'It is surfaced as context on future actions (guidance, not a hard block; positive patterns are not gate-enforced).',
+    };
+  }
+
+  return null;
+}
+
+module.exports = {
+  detectImperative,
+  suggestForceGate,
+  NEVER_RE,
+  ALWAYS_RE,
+};

package/scripts/intervention-policy.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const { resolveFeedbackDir } = require('./feedback-paths');
 const { getDecisionLogPath, readDecisionLog, collapseDecisionTimeline } = require('./decision-journal');
+const { requireLearnedModelsEntitlement } = require('./entitlement');
 
 const LABELS = ['allow', 'recall', 'verify', 'warn', 'deny'];
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -551,6 +552,10 @@ function summarizeTopTokens(model, limit = 5) {
 }
 
 function trainInterventionPolicy(examples, options = {}) {
+  requireLearnedModelsEntitlement({
+    ...(options.entitlement || {}),
+    label: 'intervention-policy training',
+  });
   const split = splitExamples(examples);
   const evaluationModel = fitNaiveBayes(split.train);
   const deployedModel = fitNaiveBayes(examples);
@@ -631,6 +636,10 @@ function buildRuntimeCandidate(params = {}) {
 }
 
 function getInterventionRecommendation(params = {}, options = {}) {
+  requireLearnedModelsEntitlement({
+    ...(options.entitlement || {}),
+    label: 'intervention-policy recommendation',
+  });
   const resolvedDir = resolveFeedbackDir({ feedbackDir: options.feedbackDir || params.feedbackDir });
   let model = options.model || loadInterventionPolicy(resolvedDir);
   const candidate = options.candidate || buildRuntimeCandidate(params);
@@ -693,6 +702,10 @@ function computeDailySeries(examples, dayCount = 14) {
 }
 
 function getInterventionPolicySummary(feedbackDir, options = {}) {
+  requireLearnedModelsEntitlement({
+    ...(options.entitlement || {}),
+    label: 'intervention-policy summary',
+  });
   const resolvedDir = resolveFeedbackDir({ feedbackDir });
   const { examples, sourceCounts } = buildExamplesFromFeedbackDir(resolvedDir);
   const model = loadInterventionPolicy(resolvedDir) || trainInterventionPolicy(examples);

package/scripts/pr-manager.js

@@ -1,11 +1,4 @@
 #!/usr/bin/env node
-/**
- * PR Manager — High-Throughput Merge & Blocker Diagnosis
- * 
- * Inspired by the 2026 GitHub 'Quick Access' update. Centralizes merge status 
- * detection and triggers autonomous self-healing for common blockers.
- */
-
 'use strict';
 
 const fs = require('node:fs');
@@ -34,6 +27,8 @@ const PASSING_BUCKETS = new Set((MERGE_QUALITY_CHECKS.passingBuckets || []).map(
 const PENDING_BUCKETS = new Set((MERGE_QUALITY_CHECKS.pendingBuckets || []).map((value) => String(value || '').toLowerCase()));
 const FAILING_BUCKETS = new Set((MERGE_QUALITY_CHECKS.failingBuckets || []).map((value) => String(value || '').toLowerCase()));
 
+const SELF_REFERENTIAL_CHECKS = new Set(MERGE_QUALITY_CHECKS.selfReferentialChecks || []);
+
 function assertSafeGhArgs(args) {
   if (!Array.isArray(args) || args.length === 0) {
     throw new Error('GH CLI args must be a non-empty array.');
@@ -119,9 +114,6 @@ function isMissingCurrentBranchPr(result, prNumber) {
     || /could not determine current branch:.*not on any branch/i.test(formatGhError(result));
 }
 
-/**
- * Fetch granular PR status using GH CLI
- */
 function getPrStatus(prNumber = '', runner = runGh) {
   const normalizedPrNumber = normalizePrNumber(prNumber);
   const args = ['pr', 'view'];
@@ -182,6 +174,9 @@ function summarizeChecks(checks = []) {
 
   for (const check of checks) {
     const name = check.name || 'unknown-check';
+
+    if (SELF_REFERENTIAL_CHECKS.has(name)) continue;
+
     const bucket = String(check.bucket || '').toLowerCase();
     if (bucket) {
       if (FAILING_BUCKETS.has(bucket)) {
@@ -225,9 +220,6 @@ function sleep(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-/**
- * Diagnose and resolve blockers autonomously
- */
 async function resolveBlockers(pr, runner = runGh) {
   const title = pr.title || 'Untitled PR';
   const mergeState = pr.mergeStateStatus || 'UNKNOWN';
@@ -241,7 +233,6 @@ async function resolveBlockers(pr, runner = runGh) {
     return { status: 'skipped', reason: 'draft' };
   }
 
-  // 1. Handle Outdated Branch (BEHIND)
   if (pr.mergeStateStatus === 'BEHIND') {
     console.log('[PR Manager] PR is behind main. Triggering auto-update...');
     const update = runner(['pr', 'update-branch', pr.number.toString()]);
@@ -250,13 +241,11 @@ async function resolveBlockers(pr, runner = runGh) {
     }
   }
 
-  // 2. Handle Merge Conflicts (DIRTY)
   if (pr.mergeStateStatus === 'DIRTY' || pr.mergeable === 'CONFLICTING') {
     console.log('[PR Manager] CRITICAL: Merge conflicts detected. Manual intervention or advanced rebase required.');
     return { status: 'blocked', reason: 'conflicts' };
   }
 
-  // 3. Handle CI Failures
   let checks = pr.statusCheckRollup || [];
   let checkSource = 'statusCheckRollup';
 
@@ -282,7 +271,6 @@ async function resolveBlockers(pr, runner = runGh) {
     return { status: 'blocked', reason: 'ci_pending', checks: checkSummary.pending, checkSource };
   }
 
-  // 4. Handle Review Blockers
   if (pr.reviewDecision === 'CHANGES_REQUESTED') {
     console.log('[PR Manager] BLOCKED: Changes requested by reviewer.');
     return { status: 'blocked', reason: 'changes_requested' };
@@ -293,8 +281,10 @@ async function resolveBlockers(pr, runner = runGh) {
     return { status: 'blocked', reason: 'review_required' };
   }
 
-  // 5. Ready to Merge
-  if (pr.mergeStateStatus === 'CLEAN' && pr.mergeable === 'MERGEABLE') {
+  if (
+    (pr.mergeStateStatus === 'CLEAN' || pr.mergeStateStatus === 'UNSTABLE')
+    && pr.mergeable === 'MERGEABLE'
+  ) {
     console.log('[PR Manager] SUCCESS: PR is ready for protected autonomous merge.');
     return { status: 'ready' };
   }
@@ -368,9 +358,6 @@ function submitTrunkMergeRequest(prNumber, runner = runGh) {
   };
 }
 
-/**
- * Perform autonomous merge
- */
 function performMerge(prInput, runner = runGh, options = {}) {
   const pr = (prInput && typeof prInput === 'object')
     ? prInput