@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/dist/hooks/pretool-guard.js

@@ -1,23 +1,23 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-GJ7JPIHN.js";
-import "./chunk-DCY2GWHC.js";
-import "./chunk-GNDJ7NJ7.js";
-import "./chunk-JBBMAPC4.js";
-import "./chunk-U32VSRNG.js";
+} from "./chunk-JXQBK323.js";
+import "./chunk-MSYSUSY6.js";
+import "./chunk-YZXYOAZ3.js";
+import "./chunk-IX6TTTI6.js";
+import "./chunk-YW452ZAX.js";
 import "./chunk-CDY4NFQG.js";
-import "./chunk-LMWBRJIP.js";
-import "./chunk-IYVOLN6A.js";
-import "./chunk-WNFJLBXI.js";
-import "./chunk-EAQEGME7.js";
+import "./chunk-7KMN5QB5.js";
+import "./chunk-2G5F2YCD.js";
+import "./chunk-QL6QTPWN.js";
+import "./chunk-5SJSSCJG.js";
 import {
   hook_decision
-} from "./chunk-EBSHN25W.js";
-import "./chunk-SL4GQ2XP.js";
-import "./chunk-J3KSS7II.js";
-import "./chunk-2YSW3CXH.js";
-import "./chunk-NEC4AT4Z.js";
+} from "./chunk-MU4LJFIV.js";
+import "./chunk-XER6SSIB.js";
+import "./chunk-4BHUPFKF.js";
+import "./chunk-3LE6VLSR.js";
+import "./chunk-DGT54IH5.js";
 
 // scripts/hooks/pretool-guard-cli.ts
 import { text } from "node:stream/consumers";

package/dist/hooks/session-lang.js

@@ -1,7 +1,4 @@
 #!/usr/bin/env tsx
-import {
-  session_language
-} from "./chunk-6V5OPIUU.js";
 import {
   agent_role_profile,
   detached_launch,
@@ -9,23 +6,24 @@ import {
   issue_cite,
   run_event_stream,
   run_event_stream_emit,
-  run_headless
-} from "./chunk-U32VSRNG.js";
+  run_headless,
+  session_language
+} from "./chunk-YW452ZAX.js";
 import {
   error_text
 } from "./chunk-CDY4NFQG.js";
 import {
   josh_environment_file
-} from "./chunk-J3KSS7II.js";
+} from "./chunk-4BHUPFKF.js";
 import {
   agent_session_environment,
   json_value,
   process_identity,
   run_carry
-} from "./chunk-2YSW3CXH.js";
+} from "./chunk-3LE6VLSR.js";
 import {
   stamp_file
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/josh/session-language-cli.ts
 import { fileURLToPath } from "node:url";
@@ -104,7 +102,14 @@ var agent_diagnostics = { check };
 import { existsSync } from "node:fs";
 import path from "node:path";
 var AGENT_COMMAND = "claude";
-var AGENT_FLAGS = ["-p", "--verbose", "--output-format", "stream-json"];
+var PERMISSION_FLAGS = ["--permission-mode", "bypassPermissions"];
+var AGENT_FLAGS = [
+  "-p",
+  "--verbose",
+  "--output-format",
+  "stream-json",
+  ...PERMISSION_FLAGS
+];
 var MODEL_FLAG = "--model";
 var EFFORT_FLAG = "--effort";
 var RESUME_FLAG = "--resume";
@@ -311,24 +316,57 @@ var STAGE = {
   // `run:carry --begin` claimed the run, and the parent is planning it.
   PLANNING: "planning",
   // The supervisor took the run over from the parent and is asking for the first offer.
-  HANDING_OFF: "handing off"
+  HANDING_OFF: "handing off",
+  // The driver answered something only a session can act on — an untriaged child, an epic left to a
+  // person — and the supervisor is waking one. The next hand-off replaces it.
+  JUDGING: "waiting on judgment",
+  // The supervisor started that session, which is now acting on the driver's answer. It is detached, so
+  // its end is the supervisor's next hand-off, which replaces this.
+  SESSION: "judgment session running",
+  // The driver's launch of a lane returned without a child: no lane was free to open, or a step after
+  // the open failed. It names no issue, so the lane's own stage ends here whatever the driver does next.
+  NO_CHILD: "no child launched"
 };
 var OPENING = "opening lane";
+var INSTALLING = "installing dependencies";
+var DISPATCHING = "dispatching";
+var LANE_STAGE = { OPENING, INSTALLING, DISPATCHING };
 function opening_lane(issue) {
   return `${OPENING} ${issue_cite.plain(issue)}`;
 }
+function installing(issue) {
+  return `${INSTALLING} ${issue_cite.plain(issue)}`;
+}
+function dispatching(issue) {
+  return `${DISPATCHING} ${issue_cite.plain(issue)}`;
+}
 async function emit(text) {
   await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SETUP, text);
 }
-function emit_in(repository, text, at) {
+function append_stage(resolve_target, text, at) {
   try {
-    const target = run_event_stream.target_of(repository);
-    run_event_stream.append(target, run_event_stream.EVENT_KIND.SETUP, text, at.toISOString());
+    const { SETUP } = run_event_stream.EVENT_KIND;
+    run_event_stream.append(resolve_target(), SETUP, text, at.toISOString());
   } catch (error) {
-    error_text.trace_swallowed("run_event_setup.emit_in", error);
+    error_text.trace_swallowed("run_event_setup.append_stage", error);
   }
 }
-var run_event_setup = { STAGE, emit, emit_in, opening_lane };
+function emit_in(repository, text, at) {
+  append_stage(() => run_event_stream.target_of(repository), text, at);
+}
+function emit_to(target, text, at) {
+  append_stage(() => target, text, at);
+}
+var run_event_setup = {
+  LANE_STAGE,
+  STAGE,
+  dispatching,
+  emit,
+  emit_in,
+  emit_to,
+  installing,
+  opening_lane
+};
 
 // scripts/backlog/backlogrun-launch.ts
 import { z } from "zod";
@@ -406,6 +444,20 @@ function started_for(git_directory, owner_pid) {
   const started_ms = Date.parse(record.started_at);
   return Number.isNaN(started_ms) ? void 0 : new Date(started_ms);
 }
+function signal_parent(pid) {
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    note_to_stderr(`process ${String(pid)} could not be signalled; its launch record is removed.`);
+  }
+}
+function stop_parent(git_directory) {
+  const record = live_launch(git_directory);
+  stamp_file.remove_stamp(launch_path(git_directory));
+  if (record === void 0) return void 0;
+  signal_parent(record.pid);
+  return record.pid;
+}
 function spawn_parent(argv, provider, target) {
   const environment = {
     ...run_headless.environment(),
@@ -440,7 +492,8 @@ var backlogrun_launch = {
   is_running,
   pending_launch,
   start,
-  started_for
+  started_for,
+  stop_parent
 };
 
 // scripts/josh/session-language-cli.ts

package/dist/hooks/stop-guard.js

@@ -3,9 +3,8 @@ import {
   RUN_LANE_LABEL,
   RUN_SOLO_LABEL,
   filing_cap,
-  git_gh_api_path,
+  gh_spawn,
   git_gh_command,
-  git_gh_exec,
   has_label_name,
   issue_citation,
   lane_background,
@@ -14,10 +13,7 @@ import {
   repo_party,
   run_cut,
   run_hold
-} from "./chunk-GNDJ7NJ7.js";
-import {
-  session_language
-} from "./chunk-6V5OPIUU.js";
+} from "./chunk-YZXYOAZ3.js";
 import {
   agent_headless,
   agent_role_profile,
@@ -25,23 +21,24 @@ import {
   lane_registry,
   run_event_stream,
   run_event_stream_emit,
-  run_headless
-} from "./chunk-U32VSRNG.js";
+  run_headless,
+  session_language
+} from "./chunk-YW452ZAX.js";
 import {
   timed_fetch
-} from "./chunk-FZ6FUSBM.js";
+} from "./chunk-723HKZO5.js";
 import "./chunk-CDY4NFQG.js";
 import {
   hook_decision
-} from "./chunk-EBSHN25W.js";
+} from "./chunk-MU4LJFIV.js";
 import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-SL4GQ2XP.js";
+} from "./chunk-XER6SSIB.js";
 import {
   lane_child_marker
-} from "./chunk-J3KSS7II.js";
+} from "./chunk-4BHUPFKF.js";
 import {
   backlog_budget,
   issue_number_shape,
@@ -50,11 +47,10 @@ import {
   process_owner_schema,
   run_carry,
   run_invocation
-} from "./chunk-2YSW3CXH.js";
+} from "./chunk-3LE6VLSR.js";
 import {
-  PROJECT_ROOT,
   stamp_file
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/hooks/stop-guard.ts
 import { text } from "node:stream/consumers";
@@ -136,7 +132,7 @@ var lane_seed_policy = {
 };
 
 // scripts/lane/lane-capacity.ts
-var DEFAULT_LANE_LIMIT = 6;
+var DEFAULT_LANE_LIMIT = 4;
 var LANE_LIMIT_KEY = "JOSH_LANE_LIMIT";
 var POSITIVE_INTEGER = /^[1-9]\d*$/u;
 var NO_LANES = 0;
@@ -245,8 +241,7 @@ var backlog_stalled = {
 var NO_FREE = 0;
 var NONE2 = 0;
 async function live_lane_count() {
-  const lanes = await lane_registry.list_lanes();
-  return lanes.filter((lane) => !lane.is_stranded).length;
+  return lane_registry.live_count(await lane_registry.list_lanes());
 }
 async function free_under(limit) {
   return lane_capacity.free_lanes(limit, await live_lane_count());
@@ -320,26 +315,6 @@ var backlog_ready = {
   ready_line
 };
 
-// scripts/gh/gh-spawn.ts
-var NO_BUDGET = 0;
-function fetch_repo_name(timeout_ms) {
-  const stdout = git_gh_exec.read_gh_api_sync({
-    path: git_gh_api_path.repo_api_path(),
-    jq_filter: ".full_name",
-    cwd: PROJECT_ROOT,
-    timeout_ms: timeout_ms ?? NO_BUDGET
-  });
-  const name = stdout?.trim();
-  return name === "" ? void 0 : name;
-}
-function get_repo_name_with_owner() {
-  return fetch_repo_name(void 0);
-}
-function get_repo_name_with_owner_within(timeout_ms) {
-  return fetch_repo_name(timeout_ms);
-}
-var gh_spawn = { get_repo_name_with_owner, get_repo_name_with_owner_within };
-
 // scripts/notify/telegram-notify.ts
 import { z } from "zod";
 var TELEGRAM_API_BASE = "https://api.telegram.org";

package/dist/josh.js

@@ -1275,10 +1275,10 @@ var BACKLOG_COMMANDS = {
   // Started from a terminal: the `backlogrun` keyword's launcher, and the board.
   backlogrun: {
     script: "scripts/backlog/backlogrun-cli.ts",
-    description: "Start a backlogrun in the background and show its board; with one already running, only show the board",
+    description: "Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it",
     category: "AI tools",
     reference: [
-      "[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]",
+      "[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop",
       "developer",
       ["files", "network", "processes"]
     ]
@@ -1388,6 +1388,12 @@ var GUARD_COMMANDS = {
 // scripts/josh/josh-commands-issue.ts
 var ISSUES_WITH_REPO = "<issue...> [--repo <owner/repo>]";
 var ISSUE_COMMANDS = {
+  "issue:ack": {
+    script: "scripts/issue/issue-ack-cli.ts",
+    description: "Record that the run read a person's update to its issue, printing the update it acknowledges",
+    category: "AI tools",
+    reference: ["<issue>", "automation", ["network"]]
+  },
   "issue:read": {
     script: "scripts/issue/issue-read-cli.ts",
     description: "Print each issue's title, body and every comment on it, in one call",
@@ -1486,7 +1492,7 @@ var LANE_COMMANDS = {
   },
   "lane:prune": {
     ...LANE_ARGUMENTS,
-    description: "Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root",
+    description: "Close every lane an interruption left without its work tree and every spent lane, then sweep unregistered leftovers under the lanes root",
     category: "AI tools",
     reference: ["", "automation", ["files", "git"]],
     default_script_arguments: ["prune"]
@@ -1518,6 +1524,14 @@ var LANE_COMMANDS = {
     category: "AI tools",
     reference: ["<issue> [--stash <message>]", "automation", ["files", "git", "processes"]]
   },
+  // `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+  "lane:restart": {
+    script: "scripts/lane/lane-restart-cli.ts",
+    tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+    description: "Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session \u2014 not counted as an outage or a failure",
+    category: "AI tools",
+    reference: ["<issue>", "developer", ["files", "git", "processes", "network"]]
+  },
   // A live run's lane limit: `.env` is read so the bare form reports the
   // `JOSH_LANE_LIMIT` a person set there when no override stands.
   "lane:limit": {
@@ -1538,7 +1552,7 @@ var LANE_COMMANDS = {
   },
   "lane:stats": {
     ...MEASURE_ARGUMENTS,
-    description: "Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it",
+    description: "Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those",
     category: "AI tools",
     reference: ["--period <days> [--limit <lane-limit>]", "maintainer", ["none"]],
     default_script_arguments: ["stats"]
@@ -1905,17 +1919,27 @@ import { availableParallelism as availableParallelism4 } from "node:os";
 // scripts/lib/status-icons.ts
 var FAIL_ICON = "\u2717";
 var PASS_ICON = "\u2714";
-var status_icons = { FAIL_ICON, PASS_ICON };
+var WARN_ICON = "\u26A0";
+var status_icons = { FAIL_ICON, PASS_ICON, WARN_ICON };
 
 // scripts/josh/josh-verdict.ts
-var { FAIL_ICON: FAIL_ICON2, PASS_ICON: PASS_ICON2 } = status_icons;
+var { FAIL_ICON: FAIL_ICON2, PASS_ICON: PASS_ICON2, WARN_ICON: WARN_ICON2 } = status_icons;
 var GATE_SUBJECT = "verification gate";
 var GATE_PASSED_PREFIX = `${PASS_ICON2} ${GATE_SUBJECT} passed`;
 var GATE_FAILED_PREFIX = `${FAIL_ICON2} ${GATE_SUBJECT} failed`;
+var GATE_UNVERIFIED_PREFIX = `${WARN_ICON2} ${GATE_SUBJECT} not verified`;
 var PASSED_VERDICT = "passed";
 var FAILED_VERDICT = "failed";
-function format_gate_passed(step_count, total) {
-  return `${GATE_PASSED_PREFIX} (${step_count} checks) in ${total}.`;
+var UNVERIFIED_VERDICT = "unverified";
+function format_counts(counts) {
+  if (counts.skipped === 0) return `${String(counts.ran)} checks`;
+  return `${String(counts.ran)} ran, ${String(counts.skipped)} skipped`;
+}
+function format_gate_passed(counts, total) {
+  return `${GATE_PASSED_PREFIX} (${format_counts(counts)}) in ${total}.`;
+}
+function format_gate_unverified(skipped, total) {
+  return `${GATE_UNVERIFIED_PREFIX} (0 ran, ${String(skipped)} skipped) in ${total}.`;
 }
 function format_gate_failed(failed_labels, total) {
   return `${GATE_FAILED_PREFIX}: ${failed_labels} (${total})`;
@@ -1930,13 +1954,16 @@ function read_verdict(line) {
   const trimmed = line.trimStart();
   if (trimmed.startsWith(GATE_FAILED_PREFIX)) return FAILED_VERDICT;
   if (trimmed.startsWith(GATE_PASSED_PREFIX)) return PASSED_VERDICT;
+  if (trimmed.startsWith(GATE_UNVERIFIED_PREFIX)) return UNVERIFIED_VERDICT;
   return void 0;
 }
 var josh_verdict = {
   PASSED_VERDICT,
   FAILED_VERDICT,
+  UNVERIFIED_VERDICT,
   format_gate_passed,
   format_gate_failed,
+  format_gate_unverified,
   GATE_OPENING_MARK,
   GATE_OPENING_PREFIX,
   is_gate_opening,
@@ -2269,7 +2296,7 @@ var DEV_COMMANDS = {
   },
   "test:unit": {
     script: "scripts/test/test-unit-guard.ts",
-    description: "Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)",
+    description: "Run unit tests with Vitest (without Vitest: a basic project runs its own test script, others skip; fails when Vitest has no tests)",
     category: "Development",
     reference: [FILTER_ARGUMENTS, "developer", ["processes"]],
     core_weight: gate_plan.direct_unit_weight,
@@ -2513,6 +2540,22 @@ var PROJECT_COMMANDS = {
     reference: ["<dir>", "automation", ["files", "git"]],
     is_kit_only: true
   },
+  "fresh:run": {
+    script: "scripts/fresh-machine/fresh-machine-cli.ts",
+    description: "Run an install scenario in a Docker container of a machine with nothing installed, and keep the log",
+    category: "Project",
+    reference: [
+      "<pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list",
+      "maintainer",
+      ["files", "network", "processes"]
+    ]
+  },
+  "auth:setup": {
+    script: "scripts/auth/auth-setup-cli.ts",
+    description: "Save the long-lived Claude Code token `claude setup-token` prints in the macOS keychain, for josh fresh:run",
+    category: "Project",
+    reference: ["[--check]", "maintainer", ["network", "processes"]]
+  },
   init: {
     script: "scripts/init/init.ts",
     description: "Initialize config in a new project",
@@ -2529,6 +2572,12 @@ var PROJECT_COMMANDS = {
     category: "Project",
     reference: ["", "developer", ["files"]]
   },
+  uninstall: {
+    script: "scripts/uninstall/uninstall.ts",
+    description: "Remove what kit added to a project and list what is left to review by hand",
+    category: "Project",
+    reference: [`${PROFILE_ARGUMENTS} [--yes]`, "developer", ["files", "processes"]]
+  },
   "registry:migrate": {
     script: "scripts/registry-migration/migrate.ts",
     description: "Migrate a project from GitHub Packages to public npm",
@@ -2791,6 +2840,7 @@ var ALIASES = {
   pf: "profile",
   st: "start",
   sy: "sync",
+  un: "uninstall",
   rmi: "registry:migrate",
   g: "git",
   gp: "pr",
@@ -2816,9 +2866,12 @@ var ALIASES = {
   rvf: "review:findings",
   ruv: "rule:value",
   ev: "eval",
+  fr: "fresh:run",
+  as: "auth:setup",
   lsm: "lane:sample",
   lst: "lane:stats",
   lli: "lane:limit",
+  lrs: "lane:restart",
   blr: "backlogrun"
 };
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1387.0",
+  "version": "1.1435.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [
@@ -276,6 +276,7 @@
   },
   "dependencies": {
     "cli-spinners": "^3.4.0",
+    "csv-parse": "^7.0.3",
     "execa": "^10.1.0",
     "js-yaml": "^5.4.3",
     "jsonc-parser": "^3.3.1",
@@ -284,12 +285,12 @@
     "string-width": "^8.3.0",
     "terminal-link": "^5.0.0",
     "tsx": "^4.23.15",
-    "zod": "^4.6.5"
+    "zod": "^4.6.6"
   },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.12.0+sha512.2ee06ac86db554cf384421461220f0e336a487bfd41b2acd04e17a86b1487832fe45e8d1743f7fc52acc77de12d2356b536fedf8229fc483239e40b13d474449",
+      "version": "12.12.1+sha512.b7f98934c0b1f29a65f5da52f2d7f994e7faad573ffdddea1497fb4dcb5aec051590ee7c7d95a38172b4bfae103a5b83edf2ee866e11731c2cafa96063610ac5",
       "onFail": "download"
     }
   },

package/prompts/review.md

@@ -27,6 +27,28 @@ is a verification pass over the fixes, not the first review again
 
 ---
 
+## Before round 1 — the implementer's self-check
+
+**Answer these five over your own diff before the scoped pair that precedes round 1.** A round-1
+High/Medium makes round 2 due, and most of them are of a kind the implementer clears more cheaply
+than a reviewer finds: in a sample of 135 round-1 High/Medium findings, about two in three fell under one of these questions. Fix what an answer turns up; the review, its
+severity tests and the round cap are unchanged.
+
+1. **Tests pin the change** — for each condition, branch or call you added or changed, name the test
+   that turns red when it is deleted or inverted, and check its fixture actually reaches that branch
+   (no assert on a string the code never draws, no comparison against a literal copy).
+2. **Prose matches the code** — grep the docs, prompts and comments for the old wording of every
+   behavior, constant, command and heading you changed, moved or removed, `"the table above"` and
+   rewritten sentences included.
+3. **Failure is not a negative answer** — every timeout, non-zero exit or `gh` failure on a path you
+   touched returns something a caller can tell apart from `false`, `undefined` or "nothing found".
+4. **Every caller moved with it** — grep every reference to a function, list or command you changed,
+   and update each sibling path (the other CLI, the registry, the consumer side) in the same change.
+5. **The Issue is met on HEAD** — the premises you relied on hold on the current tree, and each
+   acceptance criterion is checked off one by one against the diff.
+
+---
+
 ## Review level (decided by `pnpm josh review:brief --level-only`, never by judgement)
 
 **Run `pnpm josh review:brief --level-only` and use what it prints** — `low` or `medium`, from the

package/scripts/agent/claude-agent-argv.ts

@@ -8,7 +8,19 @@ import {
 } from './agent-role-profile'
 
 const AGENT_COMMAND = 'claude'
-const AGENT_FLAGS: ReadonlyArray<string> = ['-p', '--verbose', '--output-format', 'stream-json']
+// **The permission mode is passed, not left to the checkout's `.claude/settings.json`.** Claude Code
+// ignores a project's `defaultMode: bypassPermissions` (since v2.1.257) and its `permissions.allow` in
+// a workspace whose trust dialog was never accepted — every fresh clone and every new lane worktree — so
+// a headless child stopped on approvals nobody could give. The flag sets the mode that file declares;
+// its `deny` list stays in effect (#3796).
+const PERMISSION_FLAGS: ReadonlyArray<string> = ['--permission-mode', 'bypassPermissions']
+const AGENT_FLAGS: ReadonlyArray<string> = [
+	'-p',
+	'--verbose',
+	'--output-format',
+	'stream-json',
+	...PERMISSION_FLAGS,
+]
 const MODEL_FLAG = '--model'
 const EFFORT_FLAG = '--effort'
 // Resumes a stored session by id. An `outage` re-dispatch passes the

package/scripts/auth/auth-setup-cli.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { execa } from 'execa'
+import { claude_token } from './claude-token'
+import { claude_token_output } from './claude-token-output'
+
+// `josh auth:setup` — run `claude setup-token` and keep the token it prints in the macOS keychain,
+// where `josh fresh:run` reads it. The token reaches neither the screen nor a file: it is replaced in
+// the command's output. `--check` answers whether one is saved.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const CLAUDE = 'claude'
+const SAVED = `saved: ${claude_token.VARIABLE} (macOS keychain)`
+const NO_TOKEN = 'claude setup-token printed no token, so nothing was saved.'
+const NO_KEYCHAIN = `This machine has no macOS keychain, so nothing was run. Run \`claude setup-token\` yourself and export ${claude_token.VARIABLE} — josh fresh:run reads it when the keychain has none.`
+const NOT_SAVED = 'The keychain did not keep the token. Run `pnpm josh auth:setup` again.'
+
+interface Printed {
+	decoder: TextDecoder
+	text: string
+	shown: number
+}
+
+function refuse(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+function check(): number {
+	const date = claude_token.saved_date()
+
+	if (date === undefined) {
+		return refuse(`missing: no ${claude_token.VARIABLE} saved. ${claude_token.SETUP_HINT}`)
+	}
+
+	console.info(`ok: ${claude_token.VARIABLE} saved on ${date} (macOS keychain)`)
+
+	return 0
+}
+
+function store(token: string | undefined): number {
+	if (token === undefined) return refuse(NO_TOKEN)
+
+	if (!claude_token.save(token)) return refuse(NOT_SAVED)
+
+	console.info(SAVED)
+
+	return 0
+}
+
+// The sign-in URL and any prompt are shown as they arrive; from the token on, the output is held
+// back and shown once claude ends, with the token replaced.
+function show_live(printed: Printed, chunk: Uint8Array): void {
+	printed.text += printed.decoder.decode(chunk, { stream: true })
+	const live = claude_token_output.live_length(printed.text)
+
+	process.stdout.write(printed.text.slice(printed.shown, live))
+	printed.shown = live
+}
+
+// The browser sign-in needs the terminal's stdin, so only stdout passes through josh.
+async function setup(): Promise<number> {
+	if (!claude_token.has_keychain()) return refuse(NO_KEYCHAIN)
+
+	const printed: Printed = { decoder: new TextDecoder(), text: '', shown: 0 }
+	const child = execa(CLAUDE, ['setup-token'], {
+		stdin: 'inherit',
+		stderr: 'inherit',
+		reject: false,
+	})
+
+	child.stdout.on('data', (chunk: Uint8Array) => {
+		show_live(printed, chunk)
+	})
+	const result = await child
+	const held = printed.text.slice(printed.shown) + printed.decoder.decode()
+	const { token, shown } = claude_token_output.capture(held)
+
+	process.stdout.write(shown)
+
+	if (result.failed) return refuse(`claude setup-token failed: ${result.shortMessage ?? CLAUDE}`)
+
+	return store(token)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const { values } = parseArgs({ args: [...argv], options: { check: { type: 'boolean' } } })
+
+	return values.check === true ? check() : await setup()
+}
+
+const auth_setup_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+export { auth_setup_cli }