@marcomigozzi/trailhead 0.17.0 → 0.18.0

package/plugins/trailhead/templates/trailhead-plan-review-rounds.js

@@ -8,6 +8,9 @@
 // CLI:
 //   node trailhead-plan-review-rounds.js ask   --repo <project-root> [--host claude|codex]
 //   node trailhead-plan-review-rounds.js round --choice <config|1|2|3|until> --configured <n> --history <file>
+//   node trailhead-plan-review-rounds.js budget --repo <project-root> --reviewer <name> --prompt <file>
+//   node trailhead-plan-review-rounds.js overflow --output <file> [--prompt <brief file>]
+//   node trailhead-plan-review-rounds.js run --output <file> [--timeout <seconds>] -- <cmd> [args...]
 // Prints one JSON line on stdout. Exit 0 ok / 1 error / 2 usage (message on stderr).
 //
 // Config: `plan_review` (off | on | comma list of CLIs, default off) and `plan_review.rounds`
@@ -39,11 +42,50 @@
 //   concerns) | ceiling (choice until: 5 rounds done) | exhausted (fixed choice: its rounds are
 //   spent) | continue. Every stop but converged carries `surviving`, the latest round's concerns.
 //   `config` resolves to --configured.
+//
+// budget: pre-check of one reviewer call. Estimates the prompt file's tokens as ceil(utf8 bytes / 3)
+// (an estimate on the high side for code and English, not a guarantee; `overflow` covers what it
+// misses) and compares them with cap = floor(window * 0.65), the other 35% being headroom for the
+// reviewer's own system prompt and output. The window is the per-CLI default (CONTEXT_WINDOWS, 128000
+// for any other name) or the `plan_review.context` override. Decision, first match wins: skip
+// (tokens > cap) | file (bytes > 102400, a single Linux argument over 128 KiB fails with E2BIG) | arg.
+//   {"status":"ok","reviewer","decision","bytes","tokens","window","cap","windowSource":"default"|"config",
+//    "reason"?,"pointer"?,"warnings":[]}
+// `reason` (skip) is ready to quote in PLAN-REVIEW; `pointer` (file) is the short argument to pass
+// instead of the prompt. Skip is still exit 0: the verdict is data, not a failure.
+//
+// overflow: post-check of one failed reviewer call. A pure pattern match over the captured output
+// (stdout and stderr together) for the known context-overflow and E2BIG messages. With --prompt
+// <brief file>, lines of the brief echoed back by the CLI are ignored; rate-limit lines never count.
+//   {"status":"ok","overflow":bool,"reason"?:<the matched line, trimmed and length-capped>}
+//
+// run: launches ONE reviewer call under a wall-clock deadline, so no call can outlive its bound
+// (the Bash tool's own `timeout` does not apply to a background call). `--` ends the helper's flags:
+// everything after it is the command's argv verbatim (no shell). The command gets stdin closed and its
+// stdout and stderr together go to --output (a file descriptor, truncated at start, no pipes), in its
+// own process group. At the deadline the group gets SIGTERM, then SIGKILL after a grace period (10s;
+// TRAILHEAD_REVIEW_GRACE_MS overrides it, for tests), so a child that ignores SIGTERM and its
+// descendants still end. If the helper itself gets SIGTERM, SIGINT or SIGHUP it kills the group first (exit 143, 130, 129).
+// A process that leaves the group with setsid is out of reach of the group kill, and a reviewer that
+// exits in the window after the deadline fires is still reported `timeout`.
+//   {"status":"ok"|"failed"|"timeout"|"error","exitCode":<n|null>,"signal":<s|null>,"seconds":<n>,
+//    "timeoutSeconds":<n>,"output":<file>,"reason"?:<text, for failed, timeout and error>}
+// ok = exit 0; failed = non-zero exit (or a signal) before the deadline; timeout = the deadline hit,
+// whatever the exit then was and even when the output has content (do not run `overflow` on it);
+// error = the command could not be launched (ENOENT, E2BIG, EACCES...), the error text is also written
+// into --output. All four exit 0 (the reviewer's result is data). --timeout is a positive integer,
+// default 600 seconds. A missing --output or command is a usage error (exit 2); an unwritable
+// --output is exit 1. `main` returns a Promise of the exit code for this subcommand only.
+//
+// Config `plan_review.context`: an object { "<cli>": <window in tokens> }, merged per reviewer across
+// the two files (project entry, else global entry, else default). A valid entry is a positive integer
+// no larger than 10000000; anything else warns and falls through to the next layer; a value that is
+// not an object warns and is ignored.
 
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 
 const CONFIG_REL = path.join('.trailhead', 'config.json');
 const ROSTER = ['claude', 'gemini', 'codex', 'qwen', 'kimi', 'agy', 'opencode', 'cursor-agent', 'coderabbit'];
@@ -51,7 +93,35 @@ const DEFAULT_ROUNDS = 2;
 const CEILING = 5;
 const HOSTS = ['claude', 'codex'];
 const CHOICES = ['config', '1', '2', '3', 'until'];
-const VALUED = { ask: ['repo', 'host'], round: ['choice', 'configured', 'history'] };
+const VALUED = { ask: ['repo', 'host'], round: ['choice', 'configured', 'history'], budget: ['repo', 'reviewer', 'prompt'], overflow: ['output', 'prompt'], run: ['output', 'timeout'] };
+// Default context windows in tokens; any other reviewer name gets FALLBACK_WINDOW.
+const CONTEXT_WINDOWS = { claude: 200000, gemini: 1000000, codex: 272000, qwen: 256000, kimi: 256000, agy: 1000000, opencode: 128000, 'cursor-agent': 128000, coderabbit: 128000 };
+const FALLBACK_WINDOW = 128000;
+const MAX_WINDOW = 10000000;
+const CAP_RATIO = 0.65;
+const BYTES_PER_TOKEN = 3;
+const FILE_THRESHOLD_BYTES = 102400;
+const REASON_MAX = 200;
+// Wall-clock deadline of one reviewer call: above the 540s floor agy already uses. It is wall-clock
+// (not a no-output check) because a healthy reviewer may stay quiet for minutes.
+const DEFAULT_TIMEOUT_SECONDS = 600;
+// Time between SIGTERM and SIGKILL to the reviewer's process group.
+const KILL_GRACE_MS = 10000;
+// Last resort after SIGKILL: stop waiting for an exit event that never comes.
+const EXIT_FALLBACK_MS = 2000;
+// Known context-overflow and E2BIG messages of the reviewer CLIs (case-insensitive).
+const OVERFLOW_PATTERNS = [
+  /context_length_exceeded/i,
+  /maximum context length/i,
+  /prompt is too long/i,
+  /exceeds the context window/i,
+  /input is too long/i,
+  /input token count .* exceeds the maximum/i,
+  /argument list too long/i,
+  /E2BIG/i,
+];
+// A rate-limit error can mention tokens too; it is never a context overflow.
+const RATE_LIMIT = /rate.?limit|\b429\b|too many requests/i;
 
 class Usage extends Error {}
 
@@ -61,6 +131,10 @@ function parseArgs(argv) {
   const out = { command };
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
+    if (command === 'run' && a === '--') {
+      out.cmd = argv.slice(i + 1);
+      break;
+    }
     const name = a.startsWith('--') ? a.slice(2) : null;
     if (!name || !VALUED[command].includes(name)) return { error: `usage: unknown argument ${a}` };
     const v = argv[++i];
@@ -70,6 +144,16 @@ function parseArgs(argv) {
   if (command === 'ask') {
     if (!out.repo) return { error: 'usage: missing --repo <project-root>' };
     if (out.host !== undefined && !HOSTS.includes(out.host)) return { error: `usage: --host must be one of ${HOSTS.join(', ')}` };
+  } else if (command === 'budget') {
+    if (!out.repo) return { error: 'usage: missing --repo <project-root>' };
+    if (!out.reviewer) return { error: 'usage: missing --reviewer <name>' };
+    if (!out.prompt) return { error: 'usage: missing --prompt <file>' };
+  } else if (command === 'overflow') {
+    if (!out.output) return { error: 'usage: missing --output <file>' };
+  } else if (command === 'run') {
+    if (!out.output) return { error: 'usage: missing --output <file>' };
+    if (out.timeout !== undefined && !/^[1-9]\d*$/.test(out.timeout)) return { error: 'usage: --timeout needs a positive integer (seconds)' };
+    if (!out.cmd || out.cmd.length === 0 || out.cmd[0] === '') return { error: 'usage: missing command after -- <cmd> [args...]' };
   } else {
     if (!out.choice || !CHOICES.includes(out.choice)) return { error: `usage: --choice must be one of ${CHOICES.join(', ')}` };
     if (!out.configured || !/^[1-9]\d*$/.test(out.configured)) return { error: 'usage: --configured needs a positive integer' };
@@ -100,12 +184,17 @@ function readFile(file, fs_) {
   return { cfg };
 }
 
+// Su Codex lo script vive in <codexHome>/skills/trailhead/<dir>: la config globale sta lì, non in ~/.claude.
+const CODEX_INSTALL = /[\\/]skills[\\/]trailhead[\\/](?:hooks|templates)$/;
+const codexHome = () => (CODEX_INSTALL.test(__dirname) ? path.resolve(__dirname, '..', '..', '..') : null);
+
 function globalConfigPath(env) {
-  const base = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
+  const base = codexHome() || env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
   return path.join(base, 'trailhead', 'config.json');
 }
 
 // Effective { planReview, rounds } (undefined when unset) or { error }. Nearest file wins per key.
+// `contextLayers` is every file that sets plan_review.context, nearest first (merged per reviewer later).
 function readConfig(root, env, fs_) {
   const files = [path.join(root, CONFIG_REL), globalConfigPath(env)];
   const parsed = [];
@@ -119,6 +208,7 @@ function readConfig(root, env, fs_) {
     const hit = parsed.find(({ cfg }) => has(cfg, key));
     if (hit) out[prop] = { value: hit.cfg[key], file: hit.file };
   }
+  out.contextLayers = parsed.filter(({ cfg }) => has(cfg, 'plan_review.context')).map(({ file, cfg }) => ({ value: cfg['plan_review.context'], file }));
   return out;
 }
 
@@ -207,6 +297,160 @@ function runAsk(parsed, cwd, env, fs_, deps) {
   return { code: 0, result: { status: 'ask', configured, reviewers, unknown, warnings, ...buildMenus(configured) } };
 }
 
+const validWindow = (v) => Number.isInteger(v) && v > 0 && v <= MAX_WINDOW;
+
+// Window for one reviewer: first valid entry across the layers, else the default.
+function resolveWindow(layers, reviewer, warnings) {
+  for (const { value, file } of layers) {
+    if (!isObject(value)) {
+      warnings.push(`plan_review.context in ${file} must be an object of CLI name to window tokens; ignored`);
+      continue;
+    }
+    if (!has(value, reviewer)) continue;
+    if (validWindow(value[reviewer])) return { window: value[reviewer], windowSource: 'config' };
+    warnings.push(`plan_review.context.${reviewer} in ${file} must be a positive integer of at most ${MAX_WINDOW}; ignored`);
+  }
+  return { window: has(CONTEXT_WINDOWS, reviewer) ? CONTEXT_WINDOWS[reviewer] : FALLBACK_WINDOW, windowSource: 'default' };
+}
+
+// Pure decision over the prompt size and the window. First match wins: skip, file, arg.
+function budgetDecision(bytes, window) {
+  const tokens = Math.ceil(bytes / BYTES_PER_TOKEN);
+  const cap = Math.floor(window * CAP_RATIO);
+  const decision = tokens > cap ? 'skip' : bytes > FILE_THRESHOLD_BYTES ? 'file' : 'arg';
+  return { decision, tokens, cap };
+}
+
+function runBudget(parsed, cwd, env, fs_) {
+  const cfg = readConfig(path.resolve(cwd, parsed.repo), env, fs_);
+  if (cfg.error) return { code: 1, result: { status: 'error', reason: cfg.error } };
+  const file = path.resolve(cwd, parsed.prompt);
+  let bytes;
+  try {
+    bytes = fs_.readFileSync(file).length;
+  } catch (err) {
+    return { code: 1, result: { status: 'error', reason: `cannot read ${file}: ${err && err.message ? err.message : err}` } };
+  }
+  const warnings = [];
+  const { window, windowSource } = resolveWindow(cfg.contextLayers, parsed.reviewer, warnings);
+  const { decision, tokens, cap } = budgetDecision(bytes, window);
+  const result = { status: 'ok', reviewer: parsed.reviewer, decision, bytes, tokens, window, cap, windowSource };
+  if (decision === 'skip') result.reason = `prompt too large for ${parsed.reviewer}: estimated ${tokens} tokens exceeds the cap of ${cap} (65% of its ${window}-token context window)`;
+  if (decision === 'file') result.pointer = `Read the complete review brief in ${file} and answer it exactly as it asks.`;
+  result.warnings = warnings;
+  return { code: 0, result };
+}
+
+// Pure match over captured reviewer output: the first line carrying a known overflow message.
+// Lines of the brief echoed back by the CLI (matched trimmed) and rate-limit lines never count.
+function matchOverflow(text, brief = '') {
+  const echoed = new Set(String(brief).split(/\r?\n/).map((l) => l.trim()).filter(Boolean));
+  for (const line of String(text).split(/\r?\n/)) {
+    const t = line.trim();
+    if (echoed.has(t) || RATE_LIMIT.test(t)) continue;
+    if (OVERFLOW_PATTERNS.some((re) => re.test(t))) return t.slice(0, REASON_MAX);
+  }
+  return null;
+}
+
+function runOverflow(parsed, cwd, fs_) {
+  const file = path.resolve(cwd, parsed.output);
+  let text;
+  try {
+    text = fs_.readFileSync(file, 'utf8');
+  } catch (err) {
+    return { code: 1, result: { status: 'error', reason: `cannot read ${file}: ${err && err.message ? err.message : err}` } };
+  }
+  let brief = '';
+  if (parsed.prompt) {
+    const pf = path.resolve(cwd, parsed.prompt);
+    try {
+      brief = fs_.readFileSync(pf, 'utf8');
+    } catch (err) {
+      return { code: 1, result: { status: 'error', reason: `cannot read ${pf}: ${err && err.message ? err.message : err}` } };
+    }
+  }
+  const reason = matchOverflow(text, brief);
+  return { code: 0, result: reason === null ? { status: 'ok', overflow: false } : { status: 'ok', overflow: true, reason } };
+}
+
+// Runs one reviewer call under a wall-clock deadline. Resolves { code, result }; never rejects.
+function runRun(parsed, cwd, env, deps) {
+  const file = path.resolve(cwd, parsed.output);
+  const timeoutSeconds = parsed.timeout === undefined ? DEFAULT_TIMEOUT_SECONDS : Number(parsed.timeout);
+  const graceMs = deps.graceMs !== undefined ? deps.graceMs : (/^\d+$/.test(env.TRAILHEAD_REVIEW_GRACE_MS || '') ? Number(env.TRAILHEAD_REVIEW_GRACE_MS) : KILL_GRACE_MS);
+  const base = { timeoutSeconds, output: file };
+  let fd;
+  try {
+    fd = fs.openSync(file, 'w');
+  } catch (e) {
+    return Promise.resolve({ code: 1, result: { status: 'error', reason: `cannot write ${file}: ${e && e.message ? e.message : e}` } });
+  }
+  const started = Date.now();
+  const seconds = () => Math.round((Date.now() - started) / 100) / 10;
+  const [cmd, ...args] = parsed.cmd;
+
+  return new Promise((resolve) => {
+    let child = null;
+    let settled = false;
+    let timedOut = false;
+    let timers = [];
+    const killGroup = (sig) => {
+      if (!child || !child.pid) return;
+      try { process.kill(-child.pid, sig); } catch (e) { /* group already gone */ }
+    };
+    const onSignal = (sig) => { killGroup('SIGKILL'); process.exit(sig === 'SIGINT' ? 130 : sig === 'SIGHUP' ? 129 : 143); };
+    const finish = (code, result) => {
+      if (settled) return;
+      settled = true;
+      timers.forEach(clearTimeout);
+      process.removeListener('SIGTERM', onSignal);
+      process.removeListener('SIGINT', onSignal);
+      process.removeListener('SIGHUP', onSignal);
+      try { fs.closeSync(fd); } catch (e) { /* already closed */ }
+      resolve({ code, result: { ...result, seconds: seconds(), ...base } });
+    };
+    const fail = (e) => {
+      const text = `trailhead run: cannot launch ${cmd}: ${e && e.message ? e.message : e}`;
+      try { fs.writeSync(fd, text + '\n'); } catch (w) { /* the reason still goes in the JSON */ }
+      finish(0, { status: 'error', exitCode: null, signal: null, reason: text });
+    };
+
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', fd, fd], detached: true, cwd });
+    } catch (e) {
+      fail(e);
+      return;
+    }
+    process.once('SIGTERM', onSignal);
+    process.once('SIGINT', onSignal);
+    process.once('SIGHUP', onSignal);
+    child.on('error', (e) => { if (!child.pid) fail(e); });
+
+    child.on('exit', (exitCode, signal) => {
+      // Stragglers of the reviewer's group never outlive the call.
+      killGroup('SIGKILL');
+      if (timedOut) {
+        finish(0, { status: 'timeout', exitCode, signal, reason: `no exit within ${timeoutSeconds}s; the process group was terminated` });
+      } else if (exitCode === 0) {
+        finish(0, { status: 'ok', exitCode, signal });
+      } else {
+        finish(0, { status: 'failed', exitCode, signal, reason: signal ? `killed by ${signal}` : `exit code ${exitCode}` });
+      }
+    });
+
+    timers.push(setTimeout(() => {
+      timedOut = true;
+      killGroup('SIGTERM');
+      timers.push(setTimeout(() => {
+        killGroup('SIGKILL');
+        // Final fallback: do not wait for an exit event a stuck descendant could delay.
+        timers.push(setTimeout(() => finish(0, { status: 'timeout', exitCode: null, signal: 'SIGKILL', reason: `no exit within ${timeoutSeconds}s; the process group was killed` }), EXIT_FALLBACK_MS));
+      }, graceMs));
+    }, timeoutSeconds * 1000));
+  });
+}
+
 const norm = (key) => key.trim().toLowerCase().replace(/\s+/g, ' ');
 const filled = (v) => typeof v === 'string' && v.trim() !== '';
 
@@ -256,7 +500,8 @@ function runRound(parsed, cwd, fs_) {
   return { code: 0, result: decide(history, parsed.choice, Number(parsed.configured)) };
 }
 
-function main(argv, { cwd, stdout, stderr, env, fs: fsMod, which, kimiHelp } = {}) {
+// Returns the exit code, or a Promise of it for the `run` subcommand (the only asynchronous one).
+function main(argv, { cwd, stdout, stderr, env, fs: fsMod, which, kimiHelp, graceMs } = {}) {
   const cwd_ = cwd || process.cwd();
   const out = stdout || process.stdout;
   const err = stderr || process.stderr;
@@ -268,9 +513,18 @@ function main(argv, { cwd, stdout, stderr, env, fs: fsMod, which, kimiHelp } = {
     err.write(parsed.error + '\n');
     return 2;
   }
+  if (parsed.command === 'run') {
+    return runRun(parsed, cwd_, env_, { graceMs }).then((r) => {
+      out.write(JSON.stringify(r.result) + '\n');
+      return r.code;
+    });
+  }
   let run;
   try {
-    run = parsed.command === 'ask' ? runAsk(parsed, cwd_, env_, fs_, { which, kimiHelp }) : runRound(parsed, cwd_, fs_);
+    if (parsed.command === 'ask') run = runAsk(parsed, cwd_, env_, fs_, { which, kimiHelp });
+    else if (parsed.command === 'budget') run = runBudget(parsed, cwd_, env_, fs_);
+    else if (parsed.command === 'overflow') run = runOverflow(parsed, cwd_, fs_);
+    else run = runRound(parsed, cwd_, fs_);
   } catch (e) {
     if (e instanceof Usage) {
       err.write(e.message + '\n');
@@ -282,8 +536,8 @@ function main(argv, { cwd, stdout, stderr, env, fs: fsMod, which, kimiHelp } = {
   return run.code;
 }
 
-module.exports = { parseArgs, readConfig, decide, main };
+module.exports = { globalConfigPath, parseArgs, readConfig, decide, budgetDecision, matchOverflow, main };
 
 if (require.main === module) {
-  process.exit(main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, env: process.env }));
+  Promise.resolve(main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, env: process.env })).then((code) => process.exit(code));
 }

package/plugins/trailhead/templates/trailhead-repo-target.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead repo target (self-contained, ships in templates/ so it reaches every
+// install channel: bin/trailhead.js copies templates/ wholesale for Claude/npm and
+// Codex). Verifies which repository `gh` will write issues to, once per session,
+// before the first tracker write. #351.
+//
+// Why: in a fork clone `gh` ranks a parent remote (`upstream`) above `origin`, or
+// honours `remote.<parent>.gh-resolved=base` (set by `gh repo fork` / `gh repo
+// set-default`), so a bare `gh issue ...` or `gh api repos/{owner}/{repo}/...` can
+// land on the parent. Seen from the resolved target the parent reports
+// isFork:false, so the fork relation is read from the `origin` side: origin is a
+// fork whose parent equals the resolved target. Limits: only the remote named
+// `origin` is read as the fork side, and only github.com URLs parse (GHES, or a fork
+// remote under another name, is not detected). When origin exists but its fork
+// relation cannot be verified (lookup failed, or not a github.com URL) the check
+// reports `skipped` rather than `ok`.
+//
+// CLI:
+//   node trailhead-repo-target.js check  [--repo <dir>]
+//   node trailhead-repo-target.js record [--repo <dir>] --target <owner/name>
+//   node trailhead-repo-target.js clear  [--repo <dir>]
+// --repo defaults to cwd; canonicalised to the project root (main worktree via the
+// git common dir) like trailhead-isolation-answer.js, so a linked worktree shares
+// the record.
+// File shape (<project root>/.trailhead/repo-target.json): { target, recordedAt, usedAt }
+// A session is an 8-hour sliding idle window (each reuse refreshes usedAt); a
+// malformed or future timestamp is invalid and the target is checked again.
+// check prints one JSON line:
+//   {"status":"ok","target"}                       plain repo, or a verified writable own fork: proceed silently
+//   {"status":"reuse","target","recordedAt","path"}  a recorded answer for this very target (usedAt refreshed)
+//   {"status":"ask","reason":"fork-parent|no-write","target","candidates":[...],"path"}
+//   {"status":"skipped","reason"}                  gh/git unavailable, origin unverifiable or any error: proceed as before
+// record validates the slug, runs `gh repo set-default <target>` when it differs
+// from the current resolution (so every later bare gh call lands there), then writes
+// the file (and adds `.trailhead/repo-target.json` to <project root>/.gitignore if
+// absent, only when the root is a git checkout): {"status":"written","target","setDefault":true|false,"path"}; if
+// set-default fails: {"status":"error","reason"} and nothing is written.
+// clear prints {"status":"cleared|absent","path"}.
+// Exit 0 on every normal outcome and on any unexpected error; exit 2 only on a
+// usage error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync, spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'repo-target.json';
+const IDLE_WINDOW_MS = 8 * 60 * 60 * 1000;
+const WRITE_PERMISSIONS = ['ADMIN', 'MAINTAIN', 'WRITE'];
+const IGNORE_LINE = `${STATE_DIR}/${STATE_FILE}`;
+// GitHub owners start with an alphanumeric (never `-`, so a slug is never read as a flag).
+const OWNER = '[A-Za-z0-9][A-Za-z0-9-]*';
+const SLUG_RE = new RegExp(`^${OWNER}\\/[A-Za-z0-9_.-]+$`);
+
+const sameSlug = (a, b) => typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase();
+
+// "owner/name" of a GitHub remote URL (https, scp-like ssh, ssh://), else null.
+function parseGithubSlug(url) {
+  if (typeof url !== 'string') return null;
+  const m = url.trim().match(/^(?:https?:\/\/(?:[^/@]+@)?github\.com\/|ssh:\/\/(?:[^/@]+@)?github\.com(?::\d+)?\/|[^/@\s]+@github\.com:)([A-Za-z0-9][A-Za-z0-9-]*)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+// Strict ISO-8601 timestamp (as written by toISOString) -> epoch ms, or null.
+function parseTime(text) {
+  if (typeof text !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(text)) return null;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+// Valid record or null (not an object, bad slug, malformed or future timestamp).
+function validateRecord(raw, nowMs) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (typeof raw.target !== 'string' || !SLUG_RE.test(raw.target)) return null;
+  const recordedAt = parseTime(raw.recordedAt);
+  const usedAt = parseTime(raw.usedAt);
+  if (recordedAt === null || usedAt === null || recordedAt > nowMs || usedAt > nowMs) return null;
+  return { target: raw.target, recordedAt: raw.recordedAt, usedAt };
+}
+
+// Slug of the parent in a `gh repo view --json parent` value, or null.
+function parentSlug(parent) {
+  if (!parent || typeof parent !== 'object') return null;
+  if (typeof parent.nameWithOwner === 'string') return parent.nameWithOwner;
+  const owner = parent.owner && typeof parent.owner === 'object' ? parent.owner.login : parent.owner;
+  return typeof owner === 'string' && typeof parent.name === 'string' ? `${owner}/${parent.name}` : null;
+}
+
+// Pure decision. facts: { target, permission, originSlug, originInfo, remotes }
+//   originInfo: parsed `gh repo view <origin>` ({isFork, parent}) or null; remotes: GitHub slugs, origin first;
+//   originExists: an `origin` remote is configured (even if not a github.com URL).
+// record: parsed file content (null/undefined = absent).
+function decide(facts, record, now) {
+  const { target, permission, originSlug, originInfo, remotes, originExists } = facts;
+  const valid = record === null || record === undefined ? null : validateRecord(record, now.getTime());
+  if (valid && now.getTime() - valid.usedAt <= IDLE_WINDOW_MS && sameSlug(valid.target, target)) {
+    return { status: 'reuse', target, recordedAt: valid.recordedAt };
+  }
+  const parent = originInfo && originInfo.isFork === true ? parentSlug(originInfo.parent) : null;
+  if (originSlug && parent && sameSlug(parent, target) && !sameSlug(originSlug, target)) {
+    return { status: 'ask', reason: 'fork-parent', target, candidates: [originSlug, target] };
+  }
+  if (typeof permission === 'string' && !WRITE_PERMISSIONS.includes(permission)) {
+    const others = (remotes || []).filter((s) => !sameSlug(s, target));
+    const candidates = [...new Set([...others, target])];
+    return { status: 'ask', reason: 'no-write', target, candidates };
+  }
+  // origin is there but its relation to the target was not verified: do not claim ok.
+  if (originExists && (!originSlug || (!sameSlug(originSlug, target) && !originInfo))) {
+    return { status: 'skipped', reason: 'origin fork relation could not be verified' };
+  }
+  return { status: 'ok', target };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (command !== 'check' && command !== 'record' && command !== 'clear') {
+    return { error: `usage: expected "check", "record" or "clear", got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  const allowed = command === 'record' ? ['--repo', '--target'] : ['--repo'];
+  let repo = null;
+  let target;
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    if (flag === '--repo') repo = argv[i];
+    else if (!SLUG_RE.test(argv[i])) return { error: `usage: --target must be owner/name, got: ${argv[i]}` };
+    else target = argv[i];
+  }
+  if (command === 'record' && target === undefined) return { error: 'usage: record needs --target' };
+  return { command, repo, target };
+}
+
+// Project root: the main worktree when dir is inside a linked worktree, else dir.
+function resolveProjectRoot(dir) {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: gitEnv() }).trim();
+    if (common && path.basename(common) === '.git') return path.dirname(common);
+    return dir;
+  } catch {
+    return dir;
+  }
+}
+
+// Default runner: run(cmd, args, { cwd }) -> { status, stdout, stderr } (status null when the binary is missing).
+function defaultRun(cmd, args, { cwd } = {}) {
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+function ghJson(run, args, cwd) {
+  const r = run('gh', args, { cwd });
+  if (!r || r.status !== 0) return null;
+  try {
+    const v = JSON.parse(r.stdout);
+    return v && typeof v === 'object' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// GitHub slugs of the clone's remotes, origin first, deduplicated.
+function remoteSlugs(run, cwd) {
+  const r = run('git', ['config', '--get-regexp', '^remote\\..*\\.url$'], { cwd });
+  if (!r || r.status !== 0) return { origin: null, originExists: false, all: [] };
+  let origin = null;
+  let originExists = false;
+  const all = [];
+  for (const line of String(r.stdout).split('\n')) {
+    const m = line.match(/^remote\.(.+)\.url\s+(.+)$/);
+    if (m && m[1] === 'origin') originExists = true;
+    const slug = m ? parseGithubSlug(m[2]) : null;
+    if (!slug) continue;
+    if (m[1] === 'origin') origin = slug;
+    all.push({ name: m[1], slug });
+  }
+  all.sort((a, b) => (a.name === 'origin' ? -1 : 0) - (b.name === 'origin' ? -1 : 0));
+  return { origin, originExists, all: [...new Set(all.map((x) => x.slug))] };
+}
+
+function readRecord(file, fsMod) {
+  let text;
+  try {
+    text = fsMod.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+// Atomic write: a unique temp in the same dir, then rename over the file.
+function writeAtomic(dir, file, text, fsMod) {
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${STATE_FILE}.${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fsMod.writeFileSync(tmp, text);
+    fsMod.renameSync(tmp, file);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+const writeResult = (stdout, result) => stdout.write(JSON.stringify(result) + '\n');
+
+function doCheck({ repoDir, file, dir, run, fsMod, now, out }) {
+  const view = ghJson(run, ['repo', 'view', '--json', 'nameWithOwner,viewerPermission'], repoDir);
+  if (!view || typeof view.nameWithOwner !== 'string') {
+    writeResult(out, { status: 'skipped', reason: 'gh could not resolve a target repository' });
+    return;
+  }
+  const target = view.nameWithOwner;
+  const { origin, originExists, all } = remoteSlugs(run, repoDir);
+  const originInfo = origin && !sameSlug(origin, target)
+    ? ghJson(run, ['repo', 'view', '--json', 'nameWithOwner,isFork,parent', '--', origin], repoDir) : null;
+  const raw = readRecord(file, fsMod);
+  const decision = decide({ target, permission: view.viewerPermission, originSlug: origin, originInfo, remotes: all, originExists }, raw, now);
+  if (decision.status === 'reuse') {
+    // Slide the idle window first: reuse is only reported once it is persisted.
+    writeAtomic(dir, file, JSON.stringify({ ...raw, usedAt: now.toISOString() }, null, 2) + '\n', fsMod);
+    writeResult(out, { ...decision, path: file });
+  } else {
+    writeResult(out, decision.status === 'ask' ? { ...decision, path: file } : decision);
+  }
+}
+
+// Adds the marker to <root>/.gitignore if absent; only in a git checkout. Best-effort.
+function ensureIgnored(root, fsMod) {
+  try {
+    if (!fsMod.existsSync(path.join(root, '.git'))) return;
+    const file = path.join(root, '.gitignore');
+    const text = fsMod.existsSync(file) ? fsMod.readFileSync(file, 'utf8') : '';
+    if (text.split(/\r?\n/).some((l) => l.trim() === IGNORE_LINE || l.trim() === '/' + IGNORE_LINE)) return;
+    fsMod.writeFileSync(file, text + (text === '' || text.endsWith('\n') ? '' : '\n') + IGNORE_LINE + '\n');
+  } catch { /* the record itself is already written */ }
+}
+
+function doRecord({ repoDir, file, dir, run, fsMod, now, out, target }) {
+  const view = ghJson(run, ['repo', 'view', '--json', 'nameWithOwner'], repoDir);
+  if (!view || typeof view.nameWithOwner !== 'string') {
+    writeResult(out, { status: 'error', reason: 'gh could not resolve the current target repository' });
+    return;
+  }
+  const needsDefault = !sameSlug(view.nameWithOwner, target);
+  if (needsDefault) {
+    const r = run('gh', ['repo', 'set-default', '--', target], { cwd: repoDir });
+    if (!r || r.status !== 0) {
+      const detail = r && r.stderr ? String(r.stderr).trim().split('\n')[0] : 'exit ' + (r ? r.status : 'unknown');
+      writeResult(out, { status: 'error', reason: `gh repo set-default ${target} failed: ${detail}` });
+      return;
+    }
+  }
+  const stamp = now.toISOString();
+  writeAtomic(dir, file, JSON.stringify({ target, recordedAt: stamp, usedAt: stamp }, null, 2) + '\n', fsMod);
+  ensureIgnored(path.dirname(dir), fsMod);
+  writeResult(out, { status: 'written', target, setDefault: needsDefault, path: file });
+}
+
+function main(argv, { cwd, stdout, fs: fsMod, now, run } = {}) {
+  const out = stdout || process.stdout;
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+  const repoDir = parsed.repo ? path.resolve(cwd || process.cwd(), parsed.repo) : (cwd || process.cwd());
+  const root = resolveProjectRoot(repoDir);
+  const dir = path.join(root, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  const ctx = { repoDir, file, dir, run: run || defaultRun, fsMod: fsMod || fs, now: now || new Date(), out, target: parsed.target };
+  try {
+    if (parsed.command === 'clear') {
+      const present = ctx.fsMod.existsSync(file);
+      if (present) ctx.fsMod.unlinkSync(file);
+      writeResult(out, { status: present ? 'cleared' : 'absent', path: file });
+    } else if (parsed.command === 'record') {
+      doRecord(ctx);
+    } else {
+      doCheck(ctx);
+    }
+  } catch (err) {
+    writeResult(out, { status: 'skipped', reason: 'error: ' + (err && err.message ? err.message : String(err)) });
+  }
+  return 0;
+}
+
+module.exports = { IDLE_WINDOW_MS, parseGithubSlug, parentSlug, decide, parseArgs, resolveProjectRoot, main, SLUG_RE };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout }));
+}