gwqadd 0.3.5 → 0.4.0

package/LICENSE

@@ -19,3 +19,34 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+This package embeds word lists derived from third-party sources:
+
+glitchdotcom/friendly-words — https://github.com/glitchdotcom/friendly-words
+
+MIT License
+
+Copyright (c) 2018 Glitch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+dariusk/corpora — https://github.com/dariusk/corpora — released under CC0
+(public domain). No attribution is required; it is given anyway.

package/README.md

@@ -99,6 +99,23 @@ So the fix is one flag:
 gwqadd feat/logout --from main
 ```
 
+## No name? Take a random one
+
+Run `gwqadd` with no branch name and it rolls one before it asks you anything:
+
+```
+│ plume-melting-bearskin   off main
+│ create it? [Y]es · [n]o, name it properly · [e]dit · [r]eroll
+```
+
+Three words, no prefix, no waiting — nothing has been sent anywhere and nothing
+created. `r` rolls again, `e` edits it, and `n` drops you into the naming help
+below, where an AI names the branch in your repository's own style.
+
+`--random` skips the confirmation and is the only naming path that works without
+a terminal, which makes it the one scripts and agents should use. `--no-random`
+(or `GWQADD_RANDOM=off`) starts at the description prompt instead.
+
 ## Naming help
 
 One question, one confirmation:
@@ -180,6 +197,8 @@ gwqadd [options] [<branch>]
 | `--expires <dur>` | hand gwq an expiry (`1h`, `7d`, …) for a throwaway worktree |
 | `--ai <cmd>` | AI CLI used to suggest names (default: autodetected) |
 | `--no-ai` | never ask an AI, even when one is installed |
+| `--random` | skip the questions and generate a name |
+| `--no-random` | start by describing the work instead of rolling a name |
 | `--no-submodules` | skip `git submodule update --init --recursive` |
 | `-f`, `--force` | move a colliding worktree directory aside instead of failing |
 | `-n`, `--no-cd` | do the work and report the path, but do not move the shell |

package/bin/gwqadd.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync, spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import { Buffer } from 'node:buffer';
 import {
@@ -34,6 +35,8 @@ OPTIONS
   --expires <dur>    hand gwq an expiry (1h, 7d, …) for a throwaway worktree
   --ai <cmd>         AI CLI used to suggest names (default: autodetected)
   --no-ai            never ask an AI, even when one is installed
+  --random           skip the questions and generate a name
+  --no-random        start by describing the work instead of rolling a name
   --no-submodules    skip \`git submodule update --init --recursive\`
   -f, --force        move a colliding worktree directory aside instead of failing
   -n, --no-cd        do the work and report the path, but do not move the shell
@@ -47,12 +50,19 @@ EXAMPLES
   ${PKG} feat/login                  branch off HEAD, worktree, cd
   ${PKG} feat/login --from main      branch off main wherever you happen to be
   ${PKG} hotfix/x --expires 1d       gwq will mark it expired after a day
-  ${PKG}                             describe the work, confirm, done
+  ${PKG}                             roll a name, confirm, done
+  ${PKG} --random                    roll a name for a script, no questions
   ${PKG} -n --json feat/login        machine-readable, shell stays put
 
 NAMING HELP
-  Run ${PKG} with no branch name and it asks one question — what you want to do,
-  in any language. An AI CLI turns that into a branch name and you confirm once:
+  Run ${PKG} with no branch name and it rolls one immediately — three words, no
+  prefix, no waiting:
+
+    Y  create it     n  name it properly     e  edit the name     r  reroll
+
+  Nothing has been sent anywhere and nothing created at that point. Press n and
+  it asks what you want to do, in any language, and hands that to an AI CLI
+  which answers with one name in this repository's own style:
 
     Y  create it        n  describe it again        e  edit the name
 
@@ -67,6 +77,10 @@ NAMING HELP
   GWQADD_AI='<cmd>'; disable with --no-ai or GWQADD_AI=off, which leaves a plain
   prompt for an ASCII name.
 
+  --no-random (or GWQADD_RANDOM=off) starts at the description prompt instead.
+  --random goes the other way and never asks; it is the only naming path that
+  works without a terminal, which is what scripts and agents should use.
+
   None of this happens with a branch name on the command line, or without a
   terminal — scripts and agents keep the plain, silent contract.
 
@@ -135,6 +149,8 @@ try {
       expires: { type: 'string' },
       ai: { type: 'string' },
       'no-ai': { type: 'boolean' },
+      random: { type: 'boolean' },
+      'no-random': { type: 'boolean' },
       'no-submodules': { type: 'boolean' },
       force: { type: 'boolean', short: 'f' },
       'no-cd': { type: 'boolean', short: 'n' },
@@ -403,6 +419,17 @@ const doSubmodules = !values['no-submodules'];
 const force = !!values.force;
 const stayOut = !!values['no-cd'];
 
+// The random-first prompt is the default; --no-random restores the 0.3.x flow
+// of describing the work to an AI straight away.
+const randomOff =
+  !!values['no-random'] ||
+  ['off', '0', 'false', 'none'].includes(process.env.GWQADD_RANDOM ?? '');
+const randomFirst = !randomOff;
+
+if (values.random && values['no-random']) {
+  die('E_VALIDATION', '--random and --no-random cannot both be given');
+}
+
 // ── interactivity ────────────────────────────────────────────────────────────
 
 const stdinTTY = !!process.stdin.isTTY;
@@ -598,6 +625,161 @@ function defaultBranch(dir) {
   return head ? head.replace(/^refs\/remotes\/origin\//, '') : '';
 }
 
+// ── word lists (generated — do not hand-edit) ────────────────────────────────
+//
+// Regenerate with `node tools/build-words.mjs`. Editing these by hand drifts
+// the counts from the recipe and discards the licence trail (I23).
+//
+// Adjectives and nouns: glitchdotcom/friendly-words, MIT (c) 2018 Glitch.
+// Gerunds: dariusk/corpora, CC0.
+//
+// The counts match `claude -w` (216 * 109 * 407 = 9,582,408 names); the words
+// deliberately do not. See the design doc for why they were not copied.
+
+const ADJECTIVES = [
+  'aback', 'abrupt', 'achieved', 'adaptable', 'aerial', 'airy', 'alike',
+  'alpine', 'amplified', 'apricot', 'ash', 'available', 'azure', 'basalt',
+  'bejeweled', 'bevel', 'bloom', 'bold', 'boundless', 'branched', 'brawny',
+  'bright', 'bronzed', 'burly', 'butternut', 'cactus', 'candied', 'caramel',
+  'carpal', 'celestial', 'chambray', 'checkered', 'chestnut', 'chisel',
+  'citrine', 'clean', 'cloudy', 'coconut', 'colossal', 'concise', 'cookie',
+  'cord', 'creative', 'cuddly', 'cyber', 'daily', 'darkened', 'decorous',
+  'delicious', 'dented', 'diamond', 'dolomite', 'dune', 'early', 'educated',
+  'elated', 'elite', 'endurable', 'equinox', 'evergreen', 'expensive',
+  'faceted', 'familiar', 'fantastic', 'fearless', 'field', 'first', 'flannel',
+  'flax', 'flower', 'foremost', 'fortune', 'freckle', 'frill', 'furtive',
+  'garrulous', 'geode', 'ginger', 'glib', 'glorious', 'goldenrod', 'graceful',
+  'grass', 'grey', 'guiltless', 'half', 'happy', 'heathered', 'helpful',
+  'hill', 'honorable', 'humane', 'hurricane', 'icy', 'important', 'innate',
+  'iodized', 'island', 'jet', 'judicious', 'juvenile', 'knotty', 'languid',
+  'lavender', 'learned', 'level', 'lime', 'lively', 'lopsided', 'lumbar',
+  'luxurious', 'magical', 'malleable', 'marble', 'marred', 'massive', 'mellow',
+  'mercurial', 'mica', 'military', 'mire', 'modest', 'mousy', 'narrow',
+  'nebula', 'nice', 'ninth', 'numerous', 'occipital', 'olivine', 'orchid',
+  'ossified', 'pale', 'past', 'pear', 'perfect', 'petalite', 'picayune',
+  'pineapple', 'plaid', 'platinum', 'plume', 'polarized', 'polyester',
+  'prairie', 'private', 'proximal', 'pyrite', 'quickest', 'quilted', 'radical',
+  'raspy', 'regal', 'repeated', 'respected', 'ringed', 'road', 'romantic',
+  'round', 'rustic', 'salt', 'sapphire', 'scented', 'season', 'sedate',
+  'separate', 'shaded', 'sheer', 'shiny', 'shrub', 'silky', 'sincere',
+  'skitter', 'slimy', 'smooth', 'solar', 'southern', 'speckle', 'spiced',
+  'spiral', 'spotless', 'spurious', 'steel', 'stone', 'strong', 'subdued',
+  'sugar', 'sumptuous', 'superb', 'sweet', 'tame', 'tartan', 'temporal',
+  'thankful', 'thoracic', 'tide', 'tiny', 'torpid', 'tropical', 'tundra',
+  'typhoon', 'unique', 'upbeat', 'valiant', 'vast', 'verbose', 'violet',
+  'volcano', 'water', 'west', 'wholesale', 'winter', 'wobbly', 'woolen',
+  'young', 'zest'
+];
+
+const GERUNDS = [
+  'abiding', 'adding', 'affording', 'amazing', 'appearing', 'asking',
+  'attracting', 'baring', 'behaving', 'blotting', 'booking', 'boxing',
+  'brushing', 'bustling', 'carrying', 'charming', 'chopping', 'clipping',
+  'colouring', 'completing', 'continuing', 'counting', 'curing', 'daring',
+  'delighting', 'deserving', 'doubling', 'dropping', 'employing', 'escaping',
+  'exercising', 'exploding', 'fastening', 'filling', 'floating', 'flying',
+  'forming', 'gathering', 'gluing', 'guessing', 'hanging', 'heating',
+  'hopping', 'hunting', 'including', 'intending', 'joining', 'kicking',
+  'knowing', 'launching', 'licking', 'listing', 'loving', 'matching',
+  'melting', 'mining', 'muddling', 'nesting', 'obeying', 'offering', 'owning',
+  'parting', 'pedaling', 'phoning', 'planning', 'poking', 'pouring',
+  'preferring', 'printing', 'pulling', 'pushing', 'raining', 'recording',
+  'rejoicing', 'reminding', 'replying', 'returning', 'rotating', 'sailing',
+  'scorching', 'sealing', 'shading', 'shining', 'signing', 'slapping',
+  'smiling', 'snoring', 'sparing', 'spotting', 'squeaking', 'standing',
+  'stepping', 'stretching', 'suggesting', 'surprising', 'taming', 'testing',
+  'ticking', 'touching', 'trading', 'trusting', 'tying', 'unpacking',
+  'wailing', 'warming', 'weighing', 'whistling', 'wondering', 'yawning'
+];
+
+const NOUNS = [
+  'aardvark', 'acorn', 'actress', 'aftermath', 'air', 'airport', 'alibi',
+  'almanac', 'aluminum', 'amp', 'ancient', 'anise', 'antimony', 'apology',
+  'appliance', 'archduke', 'armchair', 'article', 'asterisk', 'attempt',
+  'author', 'axolotl', 'bag', 'ball', 'barbecue', 'barn', 'barracuda',
+  'basket', 'bathtub', 'beak', 'bearskin', 'bedbug', 'beginner', 'beluga',
+  'bicycle', 'birch', 'bit', 'blarney', 'blouse', 'boat', 'bongo', 'booth',
+  'bow', 'braid', 'brass', 'breath', 'broccoli', 'brow', 'buckaroo', 'buffet',
+  'bun', 'butter', 'cabbage', 'cafe', 'camera', 'candytuft', 'cap', 'caption',
+  'carbon', 'caribou', 'carpet', 'carver', 'cat', 'catmint', 'ceder', 'cello',
+  'centipede', 'chair', 'change', 'chauffeur', 'chemistry', 'chevre', 'chill',
+  'chive', 'cicada', 'cirrus', 'clarinet', 'click', 'clock', 'clover', 'coat',
+  'cockroach', 'cold', 'colossus', 'comfort', 'concrete', 'conifer', 'copy',
+  'corn', 'couch', 'course', 'cowl', 'crate', 'creature', 'cricket', 'crow',
+  'cub', 'cupcake', 'curve', 'cylinder', 'dancer', 'dataset', 'decade', 'den',
+  'desk', 'dewberry', 'dichondra', 'dinghy', 'discovery', 'dogwood', 'donut',
+  'drain', 'drifter', 'drizzle', 'duckling', 'durian', 'earth', 'echo',
+  'education', 'elbow', 'elm', 'energy', 'entree', 'ermine', 'evergreen',
+  'eyebrow', 'falcon', 'farm', 'feather', 'femur', 'ferret', 'fibre', 'figure',
+  'fine', 'flag', 'flavor', 'flood', 'flyaway', 'football', 'form', 'foxtail',
+  'freedom', 'friction', 'frog', 'function', 'galley', 'garage', 'garnet',
+  'gauge', 'gemini', 'gerbera', 'ginger', 'glasses', 'glow', 'golf', 'gouda',
+  'gram', 'grey', 'group', 'guarantee', 'gull', 'haddock', 'hallway',
+  'handsaw', 'hare', 'hawthorn', 'health', 'heaven', 'hellebore', 'herring',
+  'hiss', 'homegrown', 'hoof', 'hose', 'hourglass', 'humerus', 'hydrangea',
+  'hyphen', 'icon', 'income', 'ink', 'iron', 'jacket', 'jasmine', 'jellyfish',
+  'jodhpur', 'judge', 'juniper', 'kayak', 'keyboard', 'king', 'knee', 'krill',
+  'lake', 'land', 'larkspur', 'launch', 'lead', 'legal', 'lemur', 'letter',
+  'license', 'lighter', 'limpet', 'lion', 'liver', 'lobster', 'logic', 'lunch',
+  'lychee', 'macaw', 'magician', 'mailbox', 'mallow', 'mandible', 'manta',
+  'march', 'market', 'mars', 'mastodon', 'may', 'medallion', 'memory',
+  'meteoroid', 'midnight', 'mine', 'mirror', 'molasses', 'money', 'moon',
+  'mosquito', 'mountain', 'muenster', 'museum', 'mustang', 'napkin', 'nebula',
+  'neon', 'net', 'newt', 'nitrogen', 'nurse', 'oatmeal', 'octagon', 'office',
+  'onion', 'opinion', 'orca', 'origami', 'ounce', 'owl', 'pail', 'pan',
+  'panther', 'papyrus', 'park', 'particle', 'passive', 'path', 'pea', 'pear',
+  'pencil', 'perch', 'pet', 'pharaoh', 'piccolo', 'pig', 'pin', 'piper',
+  'place', 'plant', 'platypus', 'plot', 'plutonium', 'polyester', 'porter',
+  'potato', 'prawn', 'prince', 'process', 'proof', 'ptarmigan', 'puppet',
+  'pyramid', 'quart', 'quill', 'quotation', 'radiator', 'raft', 'rainstorm',
+  'range', 'reaction', 'recess', 'region', 'repair', 'research', 'reward',
+  'riddle', 'riverbed', 'rock', 'rook', 'rosemary', 'rubidium', 'runner',
+  'saguaro', 'salary', 'salute', 'sapphire', 'saturn', 'saxophone', 'scapula',
+  'school', 'scooter', 'screen', 'seaplane', 'second', 'seer', 'server',
+  'shallot', 'shear', 'shift', 'shop', 'shroud', 'silence', 'silver', 'skull',
+  'slice', 'slipper', 'smoke', 'sneeze', 'snowman', 'soarer', 'sodalite',
+  'sole', 'soul', 'soy', 'spark', 'spectrum', 'spider', 'split', 'sprint',
+  'spy', 'stage', 'station', 'step', 'sting', 'stocking', 'story', 'streetcar',
+  'subject', 'suit', 'sundial', 'sunspot', 'surgeon', 'sweater', 'swordfish',
+  'system', 'tailor', 'tangelo', 'target', 'tartan', 'teal', 'tellurium',
+  'tent', 'textbook', 'thorium', 'throne', 'tick', 'tile', 'tip', 'toast',
+  'topaz', 'town', 'traffic', 'traveler', 'tricorne', 'trouser', 'trust',
+  'tugboat', 'turkey', 'turret', 'twine', 'uncle', 'vacation', 'variety',
+  'vein', 'vertebra', 'viola', 'viscose', 'voice', 'walk', 'walleye',
+  'warbler', 'wasp', 'wave', 'weaver', 'whale', 'whitefish', 'wineberry',
+  'wisteria', 'wolfsbane', 'woolen', 'wrinkle', 'xylophone', 'yarrow', 'zebra',
+  'zinnia'
+];
+
+// ── random names ─────────────────────────────────────────────────────────────
+
+// crypto, not Math.random: two shells started in the same second must not be
+// able to agree on a branch name. The modulo biases the first few words of each
+// list upward by about 407 / 2^32, which is invisible at any number of branches
+// a person will ever create.
+const pick = (a) => a[randomBytes(4).readUInt32BE(0) % a.length];
+const randomName = () => `${pick(ADJECTIVES)}-${pick(GERUNDS)}-${pick(NOUNS)}`;
+
+const RANDOM_TRIES = 10;
+
+// `claude -w` lets a collision become a hard error; we reroll instead. The
+// check has to happen before the name is shown, so the confirmation prompt can
+// never offer something that cannot be created (I24). Ten failures in a
+// 9,582,408-name space means our randomness is broken, not the user's luck.
+//
+// The branch check alone is enough, and a `worktreePath()` call beside it would
+// be unreachable: `git worktree list --porcelain` only prints `branch
+// refs/heads/<name>` for a worktree that has that branch checked out, and a
+// worktree with no branch prints `detached` instead. So a name a worktree holds
+// is always a name a branch holds. Verified against git before this was cut.
+function freeRandomName(dir) {
+  for (let i = 0; i < RANDOM_TRIES; i++) {
+    const name = randomName();
+    if (!hasLocalBranch(dir, name)) return name;
+  }
+  return '';
+}
+
 // ── naming (interactive only) ────────────────────────────────────────────────
 
 // Everything about the repository worth telling a model that is choosing a
@@ -837,13 +1019,16 @@ async function typeItYourself(initial = '') {
 
 // The single checkpoint before anything is created. `n` sends the user back to
 // describing the work, which is what they asked for; `e` is there because a
-// suggestion that is one word off should not cost another round trip.
-async function confirmCreate(name, base) {
+// suggestion that is one word off should not cost another round trip; `r` only
+// appears for a random name, where rerolling costs nothing at all.
+async function confirmCreate(name, base, { reroll = false } = {}) {
   log(`${dim('│')}`);
   log(`${dim('│')} ${bold(cyan(name))}   ${dim(`off ${base}`)}`);
+  const no = reroll ? '[n]o, name it properly' : '[n]o, describe again';
+  const extra = reroll ? `${dim('·')} ${dim('[r]eroll')} ` : '';
   stderr.write(
-    `${dim('│')} create it? ${dim('[Y]es')} ${dim('·')} ${dim('[n]o, describe again')} ` +
-    `${dim('·')} ${dim('[e]dit the name')} `,
+    `${dim('│')} create it? ${dim('[Y]es')} ${dim('·')} ${dim(no)} ` +
+    `${dim('·')} ${dim('[e]dit the name')} ${extra}`,
   );
   for (;;) {
     const buf = await waitForKey();
@@ -852,14 +1037,40 @@ async function confirmCreate(name, base) {
     if (c === 0x79 || c === 0x59 || c === 0x0d || c === 0x0a) { stderr.write('\n'); return { create: true }; }
     if (c === 0x6e || c === 0x4e) { stderr.write('\n'); return { again: true }; }
     if (c === 0x65 || c === 0x45) { stderr.write('\n'); return { edit: true }; }
+    if (reroll && (c === 0x72 || c === 0x52)) { stderr.write('\n'); return { reroll: true }; }
+  }
+}
+
+// The fast half of the naming layer: a name appears with no prompt, no
+// subprocess and no network, and the expensive path costs one keystroke.
+// Returns null when the user wants to describe the work to an AI instead.
+async function offerRandom(dir, baseRef) {
+  for (;;) {
+    const name = freeRandomName(dir);
+    if (!name) {
+      warn(`could not find an unused random name in ${RANDOM_TRIES} tries — name it yourself instead`);
+      return { branch: await typeItYourself(), named: 'manual' };
+    }
+    const choice = await confirmCreate(name, baseRef, { reroll: true });
+    if (choice.create) return { branch: name, named: 'random' };
+    if (choice.edit) return { branch: await typeItYourself(name), named: 'manual' };
+    if (choice.reroll) continue;
+    return null; // `n` — fall through to describing the work
   }
 }
 
 // The whole interactive path. Returns a branch name git has already accepted;
 // never runs unless there is a terminal and no positional was given.
 async function composeBranchName(dir, repo, base) {
+  // Random first: it is free, and a user who wanted to think about the name is
+  // one keystroke away from the prompt that lets them.
+  if (randomFirst || values.random) {
+    const chosen = await offerRandom(dir, base.ref);
+    if (chosen) return chosen;
+  }
+
   const ai = detectAi();
-  if (!ai) return typeItYourself();
+  if (!ai) return { branch: await typeItYourself(), named: 'manual' };
 
   const ctx = repoContext(dir, repo, base);
   const rejected = [];
@@ -870,24 +1081,24 @@ async function composeBranchName(dir, repo, base) {
       `${dim('│')} what do you want to do? ${dim('(any language)')}\n${dim('│')} ${dim('>')} `,
     );
     // An empty answer is the escape hatch out of the AI entirely.
-    if (!description) return typeItYourself();
+    if (!description) return { branch: await typeItYourself(), named: 'manual' };
 
     const res = await askAi(ai, namingPrompt(ctx, description, rejected));
     if (!res.ok) {
       warn(`${aiLabel(ai)} failed — name it yourself instead`);
       const first = (res.err || '').trim().split('\n')[0];
       if (first) log(`${dim('│')} ${dim(first.slice(0, 120))}`);
-      return typeItYourself();
+      return { branch: await typeItYourself(), named: 'manual' };
     }
     const candidates = parseCandidates(res.out);
     if (candidates.length === 0) {
       warn(`${aiLabel(ai)} returned nothing usable — name it yourself instead`);
-      return typeItYourself();
+      return { branch: await typeItYourself(), named: 'manual' };
     }
 
     const choice = await confirmCreate(candidates[0], ctx.base);
-    if (choice.create) return candidates[0];
-    if (choice.edit) return typeItYourself(candidates[0]);
+    if (choice.create) return { branch: candidates[0], named: 'ai' };
+    if (choice.edit) return { branch: await typeItYourself(candidates[0]), named: 'manual' };
     // Rejected: remember every suggestion from this round so the next prompt
     // cannot come back with a near-identical name.
     rejected.push(...candidates);
@@ -1051,17 +1262,32 @@ async function main() {
   }
 
   let branch = positionals[0];
+  let named = 'argument';
   if (branch) {
+    // A name on the command line is the user speaking; never second-guess it.
+    if (values.random) {
+      die('E_VALIDATION', '--random cannot be combined with a branch name');
+    }
     // git would reject this later with a less obvious message.
     if (!validBranchName(branch)) {
       die('E_VALIDATION', `'${branch}' is not a valid branch name`);
     }
-  } else {
-    if (isNonInteractive) {
+  } else if (isNonInteractive) {
+    // --random is the one naming path that needs no terminal: it is arithmetic
+    // over a constant array, so nothing is triggered that the caller did not
+    // ask for by name (I15).
+    if (!values.random) {
       die('E_VALIDATION', 'a branch name is required — `gwqadd <branch>`');
     }
+    branch = freeRandomName(cwd);
+    if (!branch) {
+      die('E_VALIDATION',
+        `could not find an unused random name in ${RANDOM_TRIES} tries — pass a branch name`);
+    }
+    named = 'random';
+  } else {
     // composeBranchName only ever returns a name git has already accepted.
-    branch = await composeBranchName(cwd, repo, base);
+    ({ branch, named } = await composeBranchName(cwd, repo, base));
   }
 
   const branchExisted = hasLocalBranch(cwd, branch);
@@ -1076,7 +1302,7 @@ async function main() {
   if (existing && existsSync(existing)) {
     log(`${dim('│')} ${dim('worktree already exists')}`);
     log(`${dim('└')} ${green('✓')} ${cyan(branch)} ${dim('→')} ${existing}`);
-    return finish({ repo, branch, base, path: existing, created: 'none' });
+    return finish({ repo, branch, base, path: existing, created: 'none', named });
   }
 
   // Two ways in. Without --from, `gwq add -b` creates branch and worktree in
@@ -1167,14 +1393,14 @@ async function main() {
 
   log(`${dim('└')} ${green('✓')} ${cyan(branch)} ${dim('→')} ${created}`);
   return finish({
-    repo, branch, base, path: created,
+    repo, branch, base, path: created, named,
     created: branchExisted ? 'worktree' : 'branch+worktree',
   });
 }
 
 // ── output ───────────────────────────────────────────────────────────────────
 
-async function finish({ repo, branch, base, path, created }) {
+async function finish({ repo, branch, base, path, created, named }) {
   if (isJson) {
     process.stdout.write(JSON.stringify({
       schemaVersion: SCHEMA_VERSION,
@@ -1183,6 +1409,9 @@ async function finish({ repo, branch, base, path, created }) {
       base: { ref: base.ref, sha: base.sha },
       repo: { root: repo.root, name: repo.name },
       created,
+      // How the name was chosen, so a caller can tell a name it picked from one
+      // the tool invented. Adding a field does not bump schemaVersion (I10).
+      named,
       cd: !stayOut,
     }) + '\n');
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gwqadd",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Create a branch and its gwq worktree in the repository you are in, and cd there.",
   "type": "module",
   "bin": {