@shumkov/orchestra 0.2.0 → 0.3.0

package/lib/claude-bin.js

@@ -238,10 +238,51 @@ function ensureVendoredClaudeBin(version, { logger = console } = {}) {
   return { ok: true, path: vendored, vendored: true };
 }
 
+/**
+ * Check Claude CLI OAuth health from the credentials file — FREE (no API call,
+ * no model spawn). The CLI stores its login in ~/.claude/.credentials.json under
+ * `claudeAiOauth`, with two expiries: the short-lived `expiresAt` (access token,
+ * which the CLI silently auto-refreshes) and `refreshTokenExpiresAt` (the HARD
+ * limit — once the refresh token itself ages out, auto-refresh 401s and every
+ * channels-backend turn wedges INVISIBLY: claude fires UserPromptSubmit then
+ * dies with "OAuth access token has expired", which never reaches polygram's
+ * classifier, so it degrades to a silent "⏱ went quiet"). We watch the
+ * refresh-token expiry so the daemon can refuse turns with a clear message
+ * instead of wedging.
+ *
+ * Pure + injectable (`home`/`now`) for tests.
+ *
+ * @param {{home?:string, now?:number, warnWithinMs?:number}} [opts]
+ * @returns {{state:'healthy'|'expiring'|'expired'|'unknown', reason?:string,
+ *   refreshTokenExpiresAt:?number, msLeft:?number, daysLeft:?number}}
+ */
+function checkClaudeAuthHealth({ home = os.homedir(), now = Date.now(), warnWithinMs = 3 * 86_400_000 } = {}) {
+  const credPath = path.join(home, '.claude', '.credentials.json');
+  let creds;
+  try {
+    creds = JSON.parse(fs.readFileSync(credPath, 'utf8'));
+  } catch (err) {
+    // Missing/unreadable → can't prove expiry. Report 'unknown' (caller logs it)
+    // rather than 'expired', so a transient read error never hard-refuses traffic.
+    return { state: 'unknown', reason: `credentials unreadable: ${err.code || err.message}`, refreshTokenExpiresAt: null, msLeft: null, daysLeft: null };
+  }
+  const exp = creds && creds.claudeAiOauth && creds.claudeAiOauth.refreshTokenExpiresAt;
+  if (typeof exp !== 'number') {
+    return { state: 'unknown', reason: 'no claudeAiOauth.refreshTokenExpiresAt', refreshTokenExpiresAt: null, msLeft: null, daysLeft: null };
+  }
+  const msLeft = exp - now;
+  const daysLeft = Math.round((msLeft / 86_400_000) * 10) / 10;
+  let state = 'healthy';
+  if (msLeft <= 0) state = 'expired';
+  else if (msLeft <= warnWithinMs) state = 'expiring';
+  return { state, refreshTokenExpiresAt: exp, msLeft, daysLeft };
+}
+
 module.exports = {
   resolvePinnedClaudeBin,
   verifyPinnedClaudeBin,
   ensureVendoredClaudeBin,
   vendorDir,
   CLAUDE_CLI_PINNED_VERSION,
+  checkClaudeAuthHealth,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shumkov/orchestra",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Drive interactive Claude Code CLI sessions: spawn, inject messages via the MCP channels bridge, observe turns, recover. The transport-agnostic session engine extracted from polygram, shared by polygram (Telegram) and water (WhatsApp).",
   "type": "commonjs",
   "main": "index.js",