claude-usage-limits 1.23.0 → 1.24.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/commands/defer.md

@@ -0,0 +1,47 @@
+---
+description: Put this work off until a time you name, and start nothing now
+---
+
+Do not start the work in this message. Schedule it, confirm in one line, and stop.
+
+Run, from the plugin's skill directory:
+
+```
+node skills/usage-limits/scripts/defer.js "$ARGUMENTS" --work "<the work, one item per line>"
+```
+
+Where `$ARGUMENTS` is the time the user gave. Accepted forms:
+
+- `9:50pm`, `21:50`, `9pm`, `09:05` - a clock time. A time already past today
+  means tomorrow.
+- `in 90m`, `in 2h`, `in 45 minutes`
+- `reset` - when the binding usage window resets, plus a few minutes for the
+  meter to turn over
+
+Pass the work itself in `--work`: the list of things the user asked for, one per
+line, written so a session with none of this conversation's context can act on
+it. That text is saved to disk and handed to the run when it fires. If the user
+gave no list, summarise the pending work from this session instead.
+
+Then print the single line the script returns and **write nothing else**. Do not
+start any of the work, do not read files "to prepare", do not draft a plan in
+the reply. The whole point of the command is that this turn is cheap and
+nothing happens yet.
+
+Other forms:
+
+- `node skills/usage-limits/scripts/defer.js status` - what is deferred and when
+  it fires
+- `node skills/usage-limits/scripts/defer.js cancel` - call it off
+
+## What actually happens
+
+The work is saved as a continuation and a real scheduled task is registered
+(Windows Task Scheduler, or `at`/launchd elsewhere). At the named time the same
+wake script the usage relay uses starts a fresh session in the original
+directory and hands it the saved plan. If the launch fails - a machine whose
+network is not up yet is the common one - it retries rather than giving up.
+
+If the time is unreadable or ambiguous, the script refuses and says so. It never
+picks a reading: a deferral that fires at the wrong hour while nobody is awake
+is worse than one that was never set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -620,6 +620,32 @@ which files are mid-change, what must be verified before anything is built on
 it. It is delivered as a prompt, so an instruction beats a summary. If nothing
 is written, the relay falls back to the outstanding todo list, which is worse.
 
+**It arms at the end of a reply, not in the middle of one.** Crossing the
+threshold no longer schedules anything by itself: the relay waits for the reply
+to finish, so what it carries is work that reached a boundary rather than a
+snapshot of an interruption. Past the backstop (95 per cent by default) it stops
+waiting and arms anyway, because a completion that never comes - the limit cut
+the reply off mid-sentence - is a relay that was never armed at all. That is
+what "waiting for this reply to finish before arming" means when the budget line
+says it, and it is not an error. `relay armon threshold` restores the old
+behaviour.
+
+**Being offline is not failing.** Before it launches anything the wake checks it
+can actually reach the API, and a machine that cannot is held, not spent: it
+retries on a backoff for hours rather than burning the relay on a launch that
+could not work. This exists because it happened - a relay woke on time, said
+`SSL certificate hostname mismatch` 1.5 seconds later, recorded a failure and
+deleted itself, and a night's work was lost to a router being off. A failed
+launch is also classified now: the network and a busy service buy another
+window, an invalid key or a missing CLI does not, because retrying those would
+waste the window and saying "retrying" would be a lie.
+
+Run `relay doctor` before trusting it with anything. It checks the things that
+fail silently hours later - a CLI that moved, a permission mode nobody set, a
+machine whose power plan forbids wake timers, a scheduled task this account
+cannot register, no continuation written, no network - and says which would
+bite. Every resumed run's full output is kept: `relay log --run`.
+
 The relay is off unless the user turned it on, and it only arms while there is
 an unfinished todo list or an approved plan to carry. Do not turn it on for
 them, and do not promise behaviour it does not have:
@@ -628,6 +654,8 @@ them, and do not promise behaviour it does not have:
   input to a shell on purpose; the relay uses it only to tell whether somebody
   is at the keyboard, and to show a banner.
 - In `notify` mode — the default — it raises a notification and starts nothing.
+- The resumed run opens in a window you can see. `relay show off` hides it; the
+  output is kept either way.
 - In `resume` mode it runs the CLI itself. A headless resume does **not**
   inherit the session's permission mode, so unless one was set the resumed run
   will sit waiting for an approval nobody is there to give.
@@ -810,7 +838,8 @@ stop.
 | `scripts/live.js` | The usage reading itself, taken the way Claude Code takes it for `/usage`, kept in `usage-limits-live.json` where `collect()` prefers it when newer than the cache. |
 | `scripts/drift.js` | How wrong the reading was: each correction written down against the one it replaced. Run it with no arguments for the median and worst gap measured so far, `--json` for the fields. Answer "how far behind does this plugin actually run" from here rather than from memory. |
 | `scripts/view.js`, `scripts/bars.js`, `scripts/activity.js` | The display model, the drawing in Claude's colours, and the working/idle marks the hooks leave for the panel. Not meant to be called by hand. |
-| `scripts/relay.js` | The relay: `status`, `on`/`off`, `at N`, `grace N`, `mode notify\|resume`, `permission MODE`, `thinking off\|resume\|always`, `note "<text>"`, `cancel`, `log`. |
+| `scripts/relay.js` | The relay: `status`, `on`/`off`, `at N`, `grace N`, `mode notify\|resume`, `permission MODE`, `thinking off\|resume\|always`, `armon threshold\|completion`, `backstop N`, `show on\|off`, `onfailure rearm\|stop`, `rearms N`, `offline N`, `doctor`, `note "<text>"`, `cancel`, `log [--run]`. |
+| `scripts/net.js` | Can this machine reach the API, and was a failed run the network's fault. Three probes, TLS-interception detection, and the backoff the offline retries use. |
 | `scripts/wake.js` | What the scheduler runs after the reset: re-checks the meter, then notifies or resumes. Never called by hand. |
 | `scripts/voice.js` | The local writing profile: `show`, `card`, `set "<instruction>"`, `clear`, `off`/`on`, `forget`. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |

package/skills/usage-limits/scripts/defer.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+
+// "Not now. Do it at ten."
+//
+// The relay answers a question the plugin asks itself: the window ran out, so
+// when can this be picked up? This answers a question the USER asks: I do not
+// want this started now, start it then.
+//
+// They share all the machinery below the surface - the same saved plan, the
+// same scheduled task, the same wake script - and differ in one way that
+// matters. The relay fires when a window RESETS, which is a time nobody chose
+// and which moves. A deferral fires at a time a person named, so the grace
+// minutes that let a meter settle are not added to it: 9:50 means 9:50.
+//
+//   node defer.js 9:50pm                 tonight at 21:50
+//   node defer.js 21:50 --work "..."     with the work spelled out
+//   node defer.js "in 90m"               ninety minutes from now
+//   node defer.js reset                  when the binding window resets
+//   node defer.js status                 what is deferred, and when it fires
+//   node defer.js cancel                 call it off
+//
+// The reply is deliberately one line. The whole point of the command is that
+// nothing happens now, and a paragraph explaining that would itself be the
+// thing the user was trying to avoid.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const relay = require('./relay.js');
+const host = require('./host.js');
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+
+// ---------------------------------------------------------------------------
+// When
+// ---------------------------------------------------------------------------
+
+// Turn what somebody typed into a moment.
+//
+// Deliberately narrow. Every format here is one a person actually types at a
+// terminal, and anything else is refused with the list rather than guessed at:
+// a deferral that silently fires at the wrong hour is worse than one that
+// refuses to be set.
+function parseWhen(text, now, resetsAt) {
+  const raw = String(text == null ? '' : text).trim().toLowerCase();
+  if (!raw) return { error: 'No time given.' };
+
+  // The window reset, which is the common case and the sensible default.
+  if (/^(reset|next reset|the reset|window|when it resets)$/.test(raw)) {
+    if (!Number.isFinite(resetsAt)) {
+      return { error: 'The reset time is not known right now, so name a clock time instead.' };
+    }
+    // The one case where the relay's grace IS wanted: a meter needs a moment
+    // to turn over, and this is a window reset rather than a chosen time.
+    return { at: resetsAt + 5 * MINUTE, label: 'when the window resets' };
+  }
+
+  // "in 90m", "in 2h", "in 45 minutes", "in 1.5 hours"
+  const relative = raw.match(/^in\s+([0-9]+(?:\.[0-9]+)?)\s*(m|min|mins|minute|minutes|h|hr|hrs|hour|hours)$/);
+  if (relative) {
+    const amount = Number(relative[1]);
+    if (!Number.isFinite(amount) || amount <= 0) return { error: 'That is not a length of time.' };
+    const unit = /^m/.test(relative[2]) ? MINUTE : HOUR;
+    const span = amount * unit;
+    // A year out is not a deferral, it is a mistake.
+    if (span > 14 * 24 * HOUR) return { error: 'That is more than a fortnight away.' };
+    return { at: now + span, label: 'in ' + relative[1] + (unit === MINUTE ? ' minutes' : ' hours') };
+  }
+
+  // "9:50pm", "9pm", "21:50", "09:50"
+  const clock = raw.match(/^([0-9]{1,2})(?::([0-9]{2}))?\s*(am|pm)?$/);
+  if (clock) {
+    let hour = Number(clock[1]);
+    const minute = clock[2] === undefined ? 0 : Number(clock[2]);
+    const meridiem = clock[3];
+    if (minute > 59) return { error: 'There is no such minute as ' + minute + '.' };
+    if (meridiem) {
+      if (hour < 1 || hour > 12) return { error: 'With am or pm the hour has to be 1 to 12.' };
+      if (meridiem === 'pm' && hour !== 12) hour += 12;
+      if (meridiem === 'am' && hour === 12) hour = 0;
+    } else if (hour > 23) {
+      return { error: 'There is no such hour as ' + hour + '.' };
+    } else if (clock[2] === undefined) {
+      // A bare number with no minutes and no am/pm is ambiguous - "9" could be
+      // either nine. Refuse rather than pick one.
+      return { error: 'Ambiguous: say 9am, 9pm or 09:00.' };
+    }
+    const at = new Date(now);
+    at.setHours(hour, minute, 0, 0);
+    let stamp = at.getTime();
+    // A time already past today means tomorrow. That is what a person means by
+    // "do it at nine" when they say it at eleven at night.
+    if (stamp <= now) stamp += 24 * HOUR;
+    return { at: stamp, label: formatClock(stamp) };
+  }
+
+  return {
+    error:
+      'Could not read "' + text + '" as a time. Try 9:50pm, 21:50, "in 90m", or "reset".',
+  };
+}
+
+function formatClock(stamp) {
+  const d = new Date(stamp);
+  let hour = d.getHours();
+  const meridiem = hour >= 12 ? 'PM' : 'AM';
+  hour = hour % 12 === 0 ? 12 : hour % 12;
+  const minute = String(d.getMinutes()).padStart(2, '0');
+  return hour + ':' + minute + ' ' + meridiem;
+}
+
+// "3h 12m", the same shape the rest of the plugin prints.
+function formatSpan(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 'now';
+  const minutes = Math.round(ms / MINUTE);
+  if (minutes < 60) return minutes + 'm';
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  if (hours < 24) return rest ? hours + 'h ' + rest + 'm' : hours + 'h';
+  const days = Math.floor(hours / 24);
+  return days + 'd ' + (hours % 24) + 'h';
+}
+
+// ---------------------------------------------------------------------------
+// The line
+// ---------------------------------------------------------------------------
+
+// One sentence, and it has to carry four things: that nothing was started,
+// when it will start, how far away that is, and how to call it off. Everything
+// else is noise in a command whose whole purpose is to not do things.
+function confirmation(parts) {
+  const bits = [];
+  const descriptive = parts.label && parts.label !== parts.clock && !/^in /.test(parts.label);
+  bits.push('Doing this at ' + parts.clock + (descriptive ? ' (' + parts.label + ')' : ''));
+  bits.push('in ' + formatSpan(parts.in));
+  const line = bits.join(', ') + '. ';
+  const tail = [];
+  tail.push('Nothing has been started');
+  if (parts.items) tail.push(parts.items + ' saved');
+  if (parts.resetNote) tail.push(parts.resetNote);
+  return line + tail.join('; ') + '. Run "defer cancel" to call it off.';
+}
+
+// ---------------------------------------------------------------------------
+// Doing it
+// ---------------------------------------------------------------------------
+
+function bindingReset(now) {
+  try {
+    const usage = require('./usage.js');
+    usage.setHost(host.detect(process.argv.slice(2), process.env));
+    const collected = usage.collect(now);
+    const utilization = collected && collected.utilization;
+    if (!utilization) return { resetsAt: null, percent: null };
+    let worst = null;
+    for (const key of Object.keys(utilization)) {
+      const window = utilization[key];
+      if (!window || typeof window !== 'object') continue;
+      const percent = Number(window.utilization);
+      if (!Number.isFinite(percent)) continue;
+      const resets = Date.parse(window.resets_at);
+      if (!worst || percent > worst.percent) {
+        worst = { percent, resetsAt: Number.isFinite(resets) ? resets : null };
+      }
+    }
+    return worst || { resetsAt: null, percent: null };
+  } catch (err) {
+    return { resetsAt: null, percent: null };
+  }
+}
+
+function sessionId(argv, env) {
+  const at = argv.indexOf('--session-id');
+  if (at !== -1 && argv[at + 1]) return argv[at + 1];
+  return env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || 'defer-' + Date.now().toString(36);
+}
+
+function argOf(argv, name) {
+  const at = argv.indexOf(name);
+  return at === -1 ? null : argv[at + 1] || null;
+}
+
+function plan(options) {
+  const now = options.now;
+  const binding = options.binding || { resetsAt: null, percent: null };
+  const when = parseWhen(options.when, now, binding.resetsAt);
+  if (when.error) return { ok: false, error: when.error };
+
+  const notes = [];
+  // Worth saying, because it is the difference between the deferred run having
+  // a budget and hitting the same wall again.
+  if (Number.isFinite(binding.resetsAt)) {
+    if (when.at >= binding.resetsAt) notes.push('the window will have reset by then');
+    else if (Number.isFinite(binding.percent) && binding.percent >= 80) {
+      notes.push('note: that is before the window resets at ' + formatClock(binding.resetsAt));
+    }
+  }
+  return {
+    ok: true,
+    at: when.at,
+    label: when.label,
+    clock: formatClock(when.at),
+    in: when.at - now,
+    resetNote: notes[0] || null,
+  };
+}
+
+function status(now) {
+  const state = relay.read();
+  const armed = state.armed;
+  if (!armed) return 'Nothing is deferred.';
+  const when = Number(armed.wakeAt);
+  const deferred = armed.deferred === true;
+  return (
+    (deferred ? 'Deferred' : 'Relay armed') +
+    ': ' +
+    (armed.project || path.basename(armed.cwd || '')) +
+    ' at ' +
+    formatClock(when) +
+    ' (in ' +
+    formatSpan(when - now) +
+    ')' +
+    (armed.how ? ', via ' + armed.how : '') +
+    '.'
+  );
+}
+
+function cancel() {
+  const state = relay.read();
+  if (!state.armed) return 'Nothing was deferred.';
+  const label = formatClock(Number(state.armed.wakeAt));
+  const result = relay.disarm('cancelled by hand', Date.now());
+  return result && result.ok === false
+    ? 'Could not cancel: ' + result.error
+    : 'Cancelled the run booked for ' + label + '.';
+}
+
+function main(argv, now) {
+  const args = (argv || []).filter((a) => a !== undefined);
+  const first = args.find((a) => !a.startsWith('--')) || '';
+  const at = Number.isFinite(now) ? now : Date.now();
+
+  if (first === 'status') return status(at);
+  if (first === 'cancel' || first === 'off') return cancel();
+  if (!first || first === 'help') {
+    return [
+      'defer <time> [--work "..."]   put the work off until then and start nothing now',
+      '  9:50pm | 21:50 | "in 90m" | reset',
+      'defer status                  what is deferred and when it fires',
+      'defer cancel                  call it off',
+    ].join('\n');
+  }
+
+  const binding = bindingReset(at);
+  const decided = plan({ now: at, when: first, binding });
+  if (!decided.ok) return decided.error;
+
+  const id = sessionId(args, process.env);
+  const work = argOf(args, '--work');
+  const cwd = argOf(args, '--cwd') || process.cwd();
+
+  // The plan is saved before the task is registered. A task that fires with
+  // nothing to read is worse than a plan nobody scheduled.
+  let items = null;
+  if (work) {
+    relay.saveContinuation(id, work);
+    items = work.split('\n').filter((l) => l.trim()).length + ' line' +
+      (work.split('\n').filter((l) => l.trim()).length === 1 ? '' : 's');
+  }
+
+  const armed = relay.arm({
+    now: at,
+    sessionId: id,
+    cwd,
+    hostName: host.detect(args, process.env),
+    at: decided.at,
+    binding: { percentUsed: binding.percent, resetsAt: binding.resetsAt },
+    work: { hasWork: true, pending: 1, source: 'defer', todos: [] },
+  });
+  if (!armed.ok) return 'Could not schedule it: ' + armed.error;
+
+  // Mark it as a deferral rather than a limit relay, so `status` and the next
+  // session can tell the two apart - they read the same record.
+  try {
+    const held = relay.read();
+    if (held.armed) {
+      held.armed.deferred = true;
+      held.armed.continuation = Boolean(work);
+      relay.write(held);
+    }
+  } catch (err) {
+    // The schedule is the part that matters; the label is not worth failing for.
+  }
+
+  relay.note('deferred ' + id + ' until ' + new Date(decided.at).toISOString(), at);
+  return confirmation({
+    label: decided.label,
+    clock: decided.clock,
+    in: decided.in,
+    items,
+    resetNote: decided.resetNote,
+  });
+}
+
+if (require.main === module) {
+  try {
+    process.stdout.write(main(process.argv.slice(2), Date.now()) + '\n');
+    process.exitCode = 0;
+  } catch (err) {
+    process.stderr.write('defer: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { parseWhen, formatClock, formatSpan, confirmation, plan, status, cancel, main, MINUTE, HOUR };

package/skills/usage-limits/scripts/net.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+'use strict';
+
+// Is the network actually usable, and if a run just failed, was the network
+// the reason?
+//
+// This exists because of a real failure. A relay armed overnight woke on time,
+// found nothing wrong with itself, started the CLI, and got back
+//
+//     API Error: Unable to connect to API: SSL certificate hostname mismatch
+//
+// which is what a laptop says when the wifi is off and something - a captive
+// portal, a VPN, a corporate proxy - is answering the TLS handshake in the
+// endpoint's place. The relay treated that as a failed run, recorded "failed",
+// cleared itself and deleted its own scheduled task. The work was not done, the
+// window it had waited for was wide open, and nothing was left to try again.
+//
+// The rule that follows from it: **a machine that cannot reach the API has not
+// failed, it is waiting.** Being offline is a normal state for a laptop at
+// three in the morning and it must cost a retry, never the relay.
+//
+// Nothing here uses a package. `fetch` is in Node 18+, and the only thing that
+// matters is telling three cases apart:
+//
+//   online      the endpoint answered, with anything at all including a 401
+//   offline     nothing answered - no DNS, no route, no socket
+//   intercepted something answered but it was not the endpoint. This is the
+//               nasty one, because a captive portal returns a valid HTTP
+//               response and a working TLS session for the wrong certificate,
+//               so a naive "did I get bytes back" check says yes.
+
+const MINUTE = 60 * 1000;
+
+// 401 is the correct, healthy answer from an authenticated endpoint hit without
+// a key: it proves DNS, routing, TLS and the service. Anything in the 2xx-5xx
+// range proves the same thing more loosely. Only a thrown error is offline.
+const PROBES = [
+  { name: 'api.anthropic.com', url: 'https://api.anthropic.com/v1/models' },
+  { name: 'claude.ai', url: 'https://claude.ai/robots.txt' },
+  { name: 'github.com', url: 'https://github.com/robots.txt' },
+];
+
+// The strings a TLS interception actually produces, across Node, curl and the
+// CLIs. Matched case-insensitively against the whole error chain because Node
+// buries the real reason in err.cause.
+const TLS_INTERCEPTION = /(certificate|self.signed|self_signed|hostname\/ip does not match|hostname mismatch|altname|unable to verify|cert_authority|ERR_TLS|DEPTH_ZERO|CERT_HAS_EXPIRED|UNABLE_TO_GET_ISSUER)/i;
+
+const OFFLINE = /(ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|ENETDOWN|EPIPE|ETIMEDOUT|ECONNABORTED|socket hang up|network is unreachable|getaddrinfo|fetch failed|Unable to connect|Connection (?:error|closed|reset)|dns)/i;
+
+// Failures that are the service's, not ours, and are worth waiting out rather
+// than burning the relay on. A 529 is Anthropic's own overload code.
+const TRANSIENT_SERVICE = /(\b429\b|\b500\b|\b502\b|\b503\b|\b504\b|\b529\b|overloaded|rate.?limit|too many requests|temporarily unavailable|service unavailable|internal server error|upstream|gateway|try again|timed? ?out|timeout)/i;
+
+// Failures that will still be failures in five hours. Retrying these is how a
+// relay spends a whole window re-running the same refusal.
+const PERMANENT = /(\b401\b|\b403\b|invalid.?api.?key|authentication|unauthorized|forbidden|no conversation found|not logged in|please run .?claude .?login|credit balance|billing|quota exceeded|permission denied|ENOENT|command not found|is not recognized)/i;
+
+function chain(err) {
+  const seen = [];
+  let node = err;
+  for (let depth = 0; node && depth < 6; depth++) {
+    if (node.message) seen.push(String(node.message));
+    if (node.code) seen.push(String(node.code));
+    if (node.errno) seen.push(String(node.errno));
+    node = node.cause;
+  }
+  return seen.join(' | ');
+}
+
+// One probe. Resolves rather than rejects: a probe that throws is a result.
+async function probe(target, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1000, timeoutMs || 8000));
+  const started = Date.now();
+  try {
+    const response = await fetch(target.url, {
+      method: 'GET',
+      signal: controller.signal,
+      redirect: 'manual',
+      headers: { 'user-agent': 'usage-limits-relay/1 (connectivity probe)' },
+    });
+    return { name: target.name, ok: true, status: response.status, ms: Date.now() - started };
+  } catch (err) {
+    const text = chain(err);
+    return {
+      name: target.name,
+      ok: false,
+      ms: Date.now() - started,
+      intercepted: TLS_INTERCEPTION.test(text),
+      aborted: /abort/i.test(text),
+      detail: text.split(' | ')[0] || 'unknown',
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// The question the wake asks: can this machine reach the service right now.
+//
+// Probes run together and the first success wins, because one endpoint being
+// down is not the same as having no network, and waiting for three timeouts in
+// series burns half a minute for an answer the first probe already had.
+async function reachable(options) {
+  const opts = options || {};
+  const timeoutMs = opts.timeoutMs || 8000;
+  const targets = opts.targets || PROBES;
+  let results = [];
+  try {
+    results = await Promise.all(targets.map((target) => probe(target, timeoutMs)));
+  } catch (err) {
+    return { online: false, reason: 'offline', detail: err.message, results: [] };
+  }
+  const good = results.filter((r) => r.ok);
+  if (good.length) {
+    return {
+      online: true,
+      reason: 'ok',
+      detail: good.map((r) => r.name + ' ' + r.status + ' in ' + r.ms + 'ms').join(', '),
+      results,
+    };
+  }
+  // Nothing answered. Interception is worth naming separately: the fix is not
+  // "wait for the network", it is "sign in to the wifi" or "turn the VPN off",
+  // and a message that says so saves somebody a morning.
+  if (results.some((r) => r.intercepted)) {
+    return {
+      online: false,
+      reason: 'intercepted',
+      detail: 'something answered in the endpoint\'s place - a captive portal, a VPN or a TLS-inspecting proxy. ' +
+        (results.find((r) => r.intercepted) || {}).detail,
+      results,
+    };
+  }
+  return {
+    online: false,
+    reason: 'offline',
+    detail: results.map((r) => r.name + ': ' + (r.aborted ? 'timed out' : r.detail)).join('; '),
+    results,
+  };
+}
+
+// Given the text of a failed run, decide whether trying again later is sensible.
+//
+//   wait      the network or the service. Retry; do not consume the relay.
+//   permanent a key, a login, a missing binary. Retrying wastes the window.
+//   unknown   treated as wait once and permanent after that, because an
+//             unrecognised error that repeats is not going to fix itself.
+function classify(text) {
+  const message = String(text || '');
+  if (!message.trim()) return { kind: 'unknown', why: 'the run failed without saying why' };
+  if (PERMANENT.test(message)) return { kind: 'permanent', why: 'this will still be true after the next reset' };
+  if (TLS_INTERCEPTION.test(message)) {
+    return {
+      kind: 'wait',
+      why: 'the TLS handshake did not reach the endpoint - offline, a captive portal, or a VPN in the way',
+    };
+  }
+  if (OFFLINE.test(message)) return { kind: 'wait', why: 'the machine could not reach the network' };
+  if (TRANSIENT_SERVICE.test(message)) return { kind: 'wait', why: 'the service was busy or unavailable' };
+  return { kind: 'unknown', why: 'an error this has not seen before' };
+}
+
+// How long to wait before looking again, given how many times it has already
+// looked. Gentle at first because most outages are a router restarting, then
+// backing off so an overnight outage is not a thousand wake-ups.
+function backoffMinutes(attempt, base) {
+  const start = Number.isFinite(base) ? base : 10;
+  const steps = [start, start, start * 2, start * 3, start * 6, start * 6];
+  return steps[Math.min(Math.max(0, attempt), steps.length - 1)];
+}
+
+module.exports = { reachable, probe, classify, backoffMinutes, PROBES, MINUTE };
+
+if (require.main === module) {
+  reachable({ timeoutMs: 8000 }).then((result) => {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(result.online ? 0 : 1);
+  });
+}