#!/usr/bin/env node

/**
 * set-status.mjs — canonical CLI to update a tracker row's status/note (#1428).
 *
 * data/applications.md is a shared surface with multiple readers and writers.
 * One canonical write path is safer than N agents hand-editing markdown, so
 * modes (apply Step 9, followup, batch) call this instead of editing the table.
 *
 * Usage:
 *   node set-status.mjs <tracker#|company> <state> [--note "..."] [--role "..."] [--force] [--dry-run] [--json]
 *
 * Row resolution:
 *   - --row N     → exact match on the # column, stated explicitly
 *   - --report N  → match the row whose Report cell links report #N
 *   - numeric argument → exact match on the # column; if the tracker has a
 *     duplicate # (see #1704 — merge-tracker.mjs bug, now fixed, that could
 *     assign the same # to two rows), --role narrows it, otherwise it fails
 *     ambiguous with a candidate list instead of silently editing whichever
 *     row was found first
 *   - a comma-separated list of numbers is not a company. The command updates
 *     one row, so it exits usage and prints one command per number
 *   - otherwise → company match (normalized, same key as merge-tracker dedup);
 *     multiple hits are narrowed with --role (fuzzy, role-matcher.mjs), and
 *     anything still ambiguous fails with a numbered candidate list.
 *
 * Why --row/--report exist:
 *   Tracker row IDs and report IDs are two independent counters sharing one
 *   number space. reserve-report-num.mjs treats tracker row IDs as occupied
 *   when allocating a report number, so the sequences leapfrog and never
 *   realign; every row added WITHOUT an evaluation report (backfilled rows,
 *   #1799) widens the gap permanently. A bare numeric selector is therefore
 *   genuinely ambiguous — "97" may mean row #97 or report #97, which are
 *   different applications — and the report-number-mismatch guard below fires
 *   on every such call once the counters have diverged. A guard that fires
 *   almost always trains callers to reach for --force, which disables it
 *   everywhere including the cases it was written for.
 *
 *   --row and --report remove the ambiguity instead of suppressing the check.
 *   Both state which number space the caller means, so the mismatch guard is
 *   skipped as ANSWERED rather than overridden — unlike --force, which
 *   silences it while the ambiguity is still real.
 *
 * State validation is strict against templates/states.yml (labels, ids, and
 * aliases resolve to the canonical label; anything else is rejected before the
 * tracker is touched). --note appends to the Notes cell with "; " and is
 * idempotent — re-running the same command is always safe. With --replace-note
 * OLD, --note NEW instead replaces whole notes at "; " boundaries (including
 * idempotent retries); a missing match fails without writing anything.
 *
 * The read-modify-write runs under the shared tracker lock (tracker-utils.mjs,
 * same lock as merge-tracker.mjs) and the file is replaced atomically. Only the
 * Status and Notes cells of the matched row change; every other byte of the
 * tracker round-trips untouched.
 *
 * Exit codes: 0 success (including no-op re-runs) · 1 usage error,
 * non-canonical state, unreadable states.yml, or non-retryable lock/write failure ·
 * 2 row not found or unreadable tracker · 3 ambiguous company match ·
 * 4 tracker lock timeout (busy — retry later).
 *
 * --undo takes back the row's last logged status change: it restores the
 * prior status and appends a retraction line ("-" to-state) to the ledger, so
 * every ledger reader drops the change as if it never happened. It refuses
 * when the tracker no longer shows that change's status (someone edited the
 * row since) and when the change has no known prior status.
 *
 * When the new status is Applied, the JSON output carries
 * `"followupSeedCandidate": true` — the hook point for seeding
 * data/follow-ups.md with the default cadence (#1430, not implemented here).
 *
 * When the new status is Interview and no JD is archived yet for the row
 * (no embedded `## Job Description` section, no jds/ capture), this also
 * triggers `archive-posting.mjs --report=N <url>` — the last reliable moment
 * the posting is still likely live, and the last moment before interview-prep
 * would go looking for a JD that may no longer exist (#4506). The outcome
 * travels in the JSON output as `jdArchiveTriggered`. Same never-fails-the-
 * status-change policy as follow-up seeding. With --detach-jd-archive the
 * archive is started and not waited for (`jdArchiveTriggered.detached`), still
 * bounded by CAREER_OPS_JD_ARCHIVE_TIMEOUT_MS. The web UI and the dashboard
 * pass it: they kill this script after 30s, and the archive alone can take
 * longer than that.
 *
 * Every real status change also appends one line to the transition ledger
 * (status-log.tsv, sibling of the tracker file):
 *   {tracker#}\t{date}\t{from}\t{to}\t{source}\t
 * Source is `set-status` unless --source names the caller delegating here.
 * Date defaults to today; pass --on YYYY-MM-DD when the transition actually
 * happened earlier ("they replied Tuesday"). The append is observation-only:
 * if it fails, a warning goes to stderr and the exit code is unchanged — the
 * tracker remains the source of truth for state. Read by funnel-velocity.mjs.
 *
 * Two rules the reader enforces that this writer never has to think about,
 * because it canonicalizes the prior status and always writes its own source.
 * Any other producer does have to, so they are stated here:
 *   - An unknown from- or to-state is the sentinel "-", never an empty cell.
 *     funnel-velocity.mjs reads the two columns differently: a from of "-"
 *     parses to null, meaning no prior state, while a to of "-" is preserved
 *     as the literal "-", meaning an unknown target. Any other value goes
 *     through resolveCanonicalState, so an empty cell is rejected as
 *     `unknown from-state ""` or `unknown to-state ""` for its own column,
 *     and the row is dropped.
 *   - The source column is a closed set, and VALID_SOURCES in
 *     funnel-velocity.mjs is the authority on its members. Deliberately not
 *     enumerated here: a copy of that list in prose is wrong the first time a
 *     writer is added, and it would be wrong in three files at once.
 *     A value outside the set parses but is excluded from day-math. The row
 *     is not lost and the exclusion is not silent: it is kept as an
 *     observation, recorded in unknownSources, and printed with its line
 *     number under dataQuality. Namespacing a source (say "backfill:notes")
 *     therefore keeps the row out of the day-math figures; put that detail in
 *     the note column.
 */

import { readFileSync, existsSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { createHash } from 'node:crypto';
import { extractTrackerReportNumbers, parseMarkdownLinks, soleMarkdownLink, resolveColumns, parseTrackerRow, normalizeTextKey, splitTrackerCells, trackerRowSeparator, trackerRowIdentity } from './tracker-parse.mjs';
import { roleFuzzyMatch } from './role-matcher.mjs';
import { localToday } from './lib/local-today.mjs';
import {
  resolveTrackerPath, writeFileAtomic, loadCanonicalStates, resolveCanonicalState, stripStatusDecoration, statusTextAfterDate,
  prependNote, hasNoteEntry, normalizeCompany, cell, CLI_EXIT, makeCliFailWith, makeCliFailUsage, acquireTrackerLockForCli,
  appendLedgerRows, companiesMatchIgnoringCorporateForm,
} from './tracker-utils.mjs';
import { getCareerOpsRoot, resolveTrackerPathForWrite } from './path-resolver.mjs';
import {
  claimStatusActivity, appendStatusTransition, statusLogPath, seedFollowupOnApplied, archiveJdOnInterview,
} from './lib/status-hooks.mjs';
import { parseStatusLog, replayObservations } from './funnel-velocity.mjs';

// Two roots. CODE_ROOT holds templates/states.yml, which ships with the code;
// DATA_ROOT is the user's, and getCareerOpsRoot() is the only thing that honours
// CAREER_OPS_ROOT / CAREER_OPS_DATA_DIR / the .career-ops-data marker.
//
// One constant named CAREER_OPS did both, so resolveTrackerPath() looked inside
// the checkout. AGENTS.md calls this script "the canonical (locked, validated,
// atomic) write path" and #2901 converged the web layer's /api/status onto it —
// so on any configured data root the one supported way to change a status
// answered "No tracker found at <CHECKOUT>/applications.md", naming a file the
// user never configured. Same defect #3715 fixed in the analysis scripts.
const CODE_ROOT = dirname(fileURLToPath(import.meta.url));
const DATA_ROOT = getCareerOpsRoot();
const STATES_FILE = join(CODE_ROOT, 'templates/states.yml');

// LOCK_TIMEOUT is not destructured here — that exit path is raised inside
// acquireTrackerLockForCli() itself (tracker-utils.mjs), via CLI_EXIT.LOCK_TIMEOUT.
const { OK: EXIT_OK, USAGE: EXIT_USAGE, NOT_FOUND: EXIT_NOT_FOUND, AMBIGUOUS: EXIT_AMBIGUOUS } = CLI_EXIT;

const USAGE = `Usage: node set-status.mjs <tracker#|company> <state> [--note "..."] [--role "..."] [--on YYYY-MM-DD] [--force] [--dry-run] [--json]
       node set-status.mjs --row N <state> [...]        (explicit tracker row ID)
       node set-status.mjs --report N <state> [...]     (explicit report ID)
       node set-status.mjs --report-link N <state> [...] (strict Report-cell identity)
       node set-status.mjs <tracker#|company> --undo [--dry-run] [--json]

  <tracker#|company> Row selector: tracker # (exact) or company name (normalized match)
                     A list such as 14,78 is not a company. Run one command per row.
  <state>            Canonical state from templates/states.yml (aliases accepted)
  --row N            Select by tracker # explicitly (unambiguous; skips the mismatch guard)
  --report N         Select the row whose Report cell links report #N
  --report-link N    Select an exact numeric Report link; reject malformed cells
                     and unknown current states (used by the dashboard)
  --note "..."       Append to the Notes cell ("; "-separated, idempotent)
  --note=VALUE       Pass a literal note, including text beginning with --
  --replace-note "OLD" Replace whole OLD notes with --note text; fail if neither is present
  --role "..."       Disambiguate when several rows share the company (fuzzy match)
  --on YYYY-MM-DD    Real event date for the status-log entry (defaults to today —
                     pass it when the transition happened earlier than it's recorded)
  --source NAME      Attribution for the transition ledger: set-status (default)
                     or web (a caller delegating to this script)
  --expect-tracker HASH  Require the tracker's exact UTF-8 content to match this
                     lowercase SHA-256 hash; checked under the writer lock
  --expect-row HASH  Require the selected row, every cell but Status, to match this
                     hash (trackerRowIdentity in tracker-parse.mjs); checked under
                     the writer lock
  --expect-status STATE  Require the row's current status to be STATE, unless it
                     is already <state>; checked under the writer lock
  --undo             Take back the row's last logged status change: restore the
                     prior status and retract the change from status-log.tsv.
                     Replaces <state>
  --force            Allow a numeric selector despite a report-link mismatch, or despite a
                     report-less row whose number another row claims as its report link
  --dry-run          Resolve and validate, but write nothing
  --repair-status-log  On an idempotent Applied retry, repair a missing ledger observation
  --repair-followup  On an idempotent Applied retry, repair a missing follow-up pin
  --detach-jd-archive  On a transition into Interview, start the JD archive in the
                     background instead of waiting for it (used by the web UI
                     and the dashboard, whose status calls time out at 30s)
  --json             Machine-readable output on stdout (errors included)

  Tracker row IDs and report IDs are separate counters that diverge permanently
  once any row exists without a report. Prefer --row/--report (or the company
  name) over a bare number, and prefer any of them over --force.

Examples:
  node set-status.mjs --report 12 Applied
  node set-status.mjs --report 12 Interview --note "recruiter screen booked"
  node set-status.mjs "Acme Corp" Rejected --on 2026-08-01
  node set-status.mjs "Acme Corp" Applied --role "Platform Engineer"
  node set-status.mjs --row 7 Discarded --dry-run
  node set-status.mjs --row 7 --undo`;

/**
 * Render the canonical states from states.yml for `--help`.
 *
 * A broken states.yml degrades to a pointer rather than throwing: that failure
 * belongs to the run that tries to WRITE a state, not to `--help`.
 *
 * @returns {string} The states section, or a pointer line when unreadable.
 */
function renderStatesSection() {
  let states;
  try {
    states = loadCanonicalStates(STATES_FILE);
  } catch {
    return `\nCanonical states: see ${STATES_FILE}`;
  }
  if (!states.length) return `\nCanonical states: see ${STATES_FILE}`;
  const width = Math.max(...states.map(st => st.label.length));
  const lines = states.map((st) => {
    const terminal = st.terminal ? '  (terminal)' : '';
    const desc = st.description ? `  ${st.description}` : '';
    return `  ${st.label.padEnd(width)}${desc}${terminal}`;
  });
  return [
    '',
    'Canonical states (aliases also accepted — see templates/states.yml):',
    ...lines,
    '',
    '  A terminal state ends the application. Discarded is YOUR decision or a',
    '  closed req; Rejected is theirs; SKIP means never applied for.',
  ].join('\n');
}

// ── argument parsing ─────────────────────────────────────────────

const rawArgs = process.argv.slice(2);
const positional = [];
const flags = { note: null, replaceNote: null, role: null, on: null, row: null, report: null, reportLink: null, source: null, force: false, dryRun: false, undo: false, repairStatusLog: false, repairFollowup: false, detachJdArchive: false, json: false, expectTracker: null, expectRow: null, expectStatus: null };
const VALUE_FLAGS = { '--note': 'note', '--replace-note': 'replaceNote', '--role': 'role', '--on': 'on', '--row': 'row', '--report': 'report', '--report-link': 'reportLink', '--source': 'source', '--expect-tracker': 'expectTracker', '--expect-row': 'expectRow', '--expect-status': 'expectStatus' };

/**
 * Is the caller asking for help, rather than passing "--help" as a VALUE?
 *
 * Runs before the main loop so help answers a line that still carries the bad
 * arguments from a failed run. Value positions are skipped but never validated
 * — validation stays in the loop, which owns the error messages and exit codes.
 *
 * @param {string[]} args - argv slice.
 * @returns {boolean}
 */
function wantsHelp(args) {
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (Object.hasOwn(VALUE_FLAGS, a)) { i++; continue; } // skip this flag's value
    if (a === '--help' || a === '-h') return true;
  }
  return false;
}

// Exits 0 so `cmd --help` works in CI smoke checks and `|| true` idioms.
if (wantsHelp(rawArgs)) {
  console.log(`${USAGE}\n${renderStatesSection()}`);
  process.exit(EXIT_OK);
}

// Who is driving this write. A caller that delegates here instead of touching
// the tracker itself — the web status route — needs its ledger rows to stay
// distinguishable from a CLI run's.
//
// The allow-list is narrow on purpose. The value is written to a file
// funnel-velocity.mjs parses positionally and gates on its own source
// allow-list, so an unrecognized label would be persisted here and then
// silently dropped there. Rejecting it at the boundary keeps the two ends from
// disagreeing about what a valid source is.
const WRITER_SOURCES = new Set(['set-status', 'web', 'reply-watch']);

// Before the parse loop: failUsage runs on the first bad token, and a const
// is not hoisted the way the previous function declaration was.
const failUsage = makeCliFailUsage({
  argv: rawArgs,
  usage: USAGE,
  defaultMessage: 'Expected 2 arguments: <tracker#|company> <state>',
});

for (let i = 0; i < rawArgs.length; i++) {
  const a = rawArgs[i];
  if (a.startsWith('--note=')) {
    flags.note = a.slice('--note='.length);
  } else if (a in VALUE_FLAGS) {
    // Never consume a following flag as the value: "--note --dry-run" would
    // silently disable dry-run and turn a preview into a real write.
    const value = rawArgs[i + 1];
    if (value === undefined || value.startsWith('--')) {
      failUsage(`Missing value for ${a}`);
    }
    // --row/--report name a row by number; a non-numeric value is a typo, and
    // silently treating it as "no match" would hide the mistake.
    if ((a === '--row' || a === '--report' || a === '--report-link') && !/^\d+$/.test(value)) {
      failUsage(`${a} expects a positive integer, got "${value}"`);
    }
    if (a === '--source' && !WRITER_SOURCES.has(value)) {
      failUsage(`--source expects one of ${[...WRITER_SOURCES].join(', ')}, got "${value}"`);
    }
    if ((a === '--expect-tracker' || a === '--expect-row') && (value.length !== 64 || !/^[a-f0-9]{64}$/.test(value))) {
      failUsage(`${a} expects a lowercase SHA-256 hash (64 hex characters)`);
    }
    flags[VALUE_FLAGS[a]] = value;
    i++;
  }
  else if (a === '--force') { flags.force = true; }
  else if (a === '--dry-run') { flags.dryRun = true; }
  else if (a === '--undo') { flags.undo = true; }
  else if (a === '--repair-status-log') { flags.repairStatusLog = true; }
  else if (a === '--repair-followup') { flags.repairFollowup = true; }
  else if (a === '--detach-jd-archive') { flags.detachJdArchive = true; }
  else if (a === '--json') { flags.json = true; }
  else if (a === '-h' || a.startsWith('--')) { failUsage(`Unknown flag: ${a}`); }
  else { positional.push(a); }
}

if (flags.replaceNote !== null && (!cell(flags.replaceNote) || flags.note === null || !cell(flags.note))) {
  failUsage('--replace-note requires non-empty OLD and --note NEW values');
}

// --row and --report ARE the selector, so they replace the positional one.
// Accepting both would leave two competing answers to "which row?"; refuse
// rather than pick, since picking wrong writes to the wrong application.
if ([flags.row, flags.report, flags.reportLink].filter(value => value !== null).length > 1) {
  failUsage('--row, --report and --report-link are mutually exclusive selectors');
}
const explicitSelector = flags.row !== null || flags.report !== null || flags.reportLink !== null;

if (flags.undo) {
  const conflicting = [
    [flags.note !== null, '--note'], [flags.replaceNote !== null, '--replace-note'], [flags.on !== null, '--on'],
    [flags.repairStatusLog, '--repair-status-log'], [flags.repairFollowup, '--repair-followup'],
  ].filter(([set]) => set).map(([, name]) => name);
  if (conflicting.length) failUsage(`--undo cannot be combined with ${conflicting.join(', ')}`);
  if (positional.length !== (explicitSelector ? 0 : 1)) {
    failUsage('--undo takes the row selector only, not a state');
  }
} else if (explicitSelector) {
  if (positional.length !== 1) {
    failUsage(positional.length === 0
      ? `Expected the state after ${flags.row !== null ? '--row' : flags.report !== null ? '--report' : '--report-link'}`
      : `With ${flags.row !== null ? '--row' : flags.report !== null ? '--report' : '--report-link'} the only positional argument is the state, got ${positional.length}`);
  }
} else if (positional.length !== 2) {
  failUsage(positional.length === 0 ? null : `Expected 2 arguments (selector, state), got ${positional.length}`);
}

// --on must be a real, non-future calendar date — validated before anything
// touches the tracker, same as state validation below.
if (flags.on !== null) {
  const m = /^\d{4}-\d{2}-\d{2}$/.test(flags.on);
  const d = m ? new Date(`${flags.on}T00:00:00Z`) : null;
  const roundTrips = d && !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === flags.on;
  if (!roundTrips) failUsage(`--on expects a real date as YYYY-MM-DD, got "${flags.on}"`);
  // LOCAL today, not the UTC day. At a positive UTC offset the UTC day is
  // still yesterday for the first hours of the local day, so comparing against
  // it rejected the user's own today: `TZ=Pacific/Auckland --on 2026-08-16`
  // failed with "date is in the future" on 2026-08-16 (#2932). The round-trip
  // check above deliberately stays on UTC — that is date PARSING, not "what
  // day is it here".
  if (flags.on > localToday()) failUsage(`--on date is in the future: "${flags.on}"`);
}

const selector = explicitSelector ? null : positional[0];
const stateInput = explicitSelector ? positional[0] : positional[1];

// A bare positional number is the ambiguous case the mismatch guard exists for.
// --row/--report are numeric too but carry an explicit number space, so they
// must not be treated as ambiguous.
const isBareNumericSelector = selector !== null && /^\d+$/.test(selector);

// Shared with every other canonical tracker-writer CLI (tracker-utils.mjs) so
// the JSON-vs-human error contract can't drift between them.
const failWith = makeCliFailWith(flags.json);

// ── state validation (before anything touches the tracker) ──────

let states;
try {
  states = loadCanonicalStates(STATES_FILE);
} catch (err) {
  failWith(EXIT_USAGE, 'states-error', `Cannot load canonical states from ${STATES_FILE}: ${err.message}`);
}
const requestedStatus = flags.undo ? null : resolveCanonicalState(stateInput, states);
if (!flags.undo && !requestedStatus) {
  const valid = states.map(s => s.label).join(' · ');
  failWith(EXIT_USAGE, 'invalid-state', `"${stateInput}" is not a canonical state. Valid states: ${valid}`);
}

// "14,78" is one argv token. It is not a company, and this command writes one
// row. Checked after the state is known, so a bad state still wins, and before
// the tracker is opened, so a missing file does not hide the usage error.
// "Acme, Inc." stays a company name: a non-numeric piece is not an id list.
function trackerIdList(value) {
  if (typeof value !== 'string' || !value.includes(',')) return null;
  const parts = value.split(',').map((part) => part.trim());
  if (parts.length < 2) return null;
  if (!parts.every((part) => part === '' || /^\d+$/.test(part))) return null;
  if (!parts.some((part) => /^\d+$/.test(part))) return null;
  return parts;
}

if (selector !== null) {
  const idList = trackerIdList(selector);
  if (idList) {
    const nums = idList.filter((part) => /^\d+$/.test(part));
    const shown = nums.slice(0, 8);
    const action = flags.undo ? '--undo' : requestedStatus;
    // These numbers are tracker rows. A bare `14 Applied` is rejected when that
    // row's report id differs, so the command that means "tracker row" is --row.
    const lines = shown.map((id) => `node set-status.mjs --row ${id} ${action}`);
    const extra = nums.length - shown.length;
    const more = extra > 0 ? `\n... and ${extra} more` : '';
    const empty = idList.some((part) => part === '') ? ' The list has an empty slot.' : '';
    failUsage(`set-status updates one row.${empty} Run one command per tracker number:\n${lines.join('\n')}${more}`);
  }
}

// ── tracker access ───────────────────────────────────────────────

const APPS_FILE = resolveTrackerPath(DATA_ROOT);
if (!existsSync(APPS_FILE)) {
  // The read path falls back to <root>/applications.md when nothing exists yet.
  // A first evaluation writes data/applications.md (or CAREER_OPS_TRACKER).
  // Naming the fallback points the first status change at a file that will never appear.
  const writePath = resolveTrackerPathForWrite(DATA_ROOT);
  failWith(EXIT_NOT_FOUND, 'no-tracker', `No tracker found at ${writePath}. The tracker is created when you evaluate your first offer.`);
}

/**
 * Reduce a selector's candidate list to exactly one row, or exit.
 *
 * Every selector path shares one shape: match, optionally narrow by --role,
 * refuse to guess between survivors, return the unique row. Only the predicate
 * and the two messages differ.
 *
 * Centralising it matters more than the duplication it removes. **Failing
 * closed on 2+ candidates is the #1704 fix** — a stale tracker # reused across
 * two rows makes "the first match" a silent coin flip on which company gets
 * edited. While that behaviour lived in three copies, a future change that
 * reintroduced first-match-wins in one branch would have been invisible in the
 * other two. There is now one place to get it wrong, and one place to test.
 *
 * Note --role only ever *narrows* here; it never validates a lone match. That
 * is deliberate and load-bearing: the #2009 check downstream compares the
 * resolved row against --role precisely because a selector matching exactly
 * one row never reaches the narrowing branch. Do not "fix" that by validating
 * here — the two checks answer different questions.
 *
 * @param {object[]} matches - Rows matching the selector, before --role narrowing.
 * @param {object} messages - Selector-specific failure text.
 * @param {string} messages.notFound - Message when nothing matched.
 * @param {(count: number, listing: string) => string} messages.ambiguous - Message when 2+ survive.
 * @returns {object} The single matched row. Exits the process on 0 or 2+ matches.
 */
function resolveCandidates(matches, { notFound, ambiguous }) {
  if (matches.length === 0) {
    failWith(EXIT_NOT_FOUND, 'not-found', notFound);
  }
  if (matches.length > 1 && flags.role) {
    const narrowed = matches.filter(r => roleFuzzyMatch(r.role, flags.role));
    if (narrowed.length === 1) return narrowed[0];
    // Fall through with the original list so the candidates stay visible.
  }
  if (matches.length > 1) {
    const candidates = matches.map(r => ({ num: r.num, company: r.company, role: r.role }));
    const listing = candidates.map(c => `#${c.num}\t${c.company}\t${c.role}`).join('\n');
    failWith(EXIT_AMBIGUOUS, 'ambiguous', ambiguous(matches.length, listing), { candidates });
  }
  return matches[0];
}

/**
 * Find the tracker row matching the CLI selector.
 *
 * @param {object[]} rows - Parsed data rows (parseTrackerRow output + lineIdx).
 * @returns {object} The single matched row. Exits the process on 0 or 2+ matches.
 */
function resolveRow(rows) {
  // --report-link is the dashboard's strict identity selector: only the
  // dedicated Report cell may identify the row, and every candidate must have
  // exactly one well-formed link. References in Notes or malformed cells are
  // rejected instead of being skipped in favour of another row.
  if (flags.reportLink !== null) {
    const matches = [];
    for (const row of rows) {
      if (!parseMarkdownLinks(String(row.report ?? '')).some(link => link.label === flags.reportLink)) continue;
      if (!soleMarkdownLink(row.report)) {
        failWith(EXIT_AMBIGUOUS, 'malformed-report', `Malformed Report cell for report #${flags.reportLink}: expected exactly one report link`);
      }
      matches.push(row);
    }
    return resolveCandidates(matches, {
      notFound: `No tracker row has Report link #${flags.reportLink}`,
      ambiguous: () => `Report #${flags.reportLink} occurs in multiple tracker rows`,
    });
  }

  // --report N: resolve through the Report cell, which is the number space a
  // caller reading a report filename actually has in hand.
  if (flags.report !== null) {
    const num = parseInt(flags.report, 10);
    return resolveCandidates(
      rows.filter(r => extractTrackerReportNumbers(r.report, r.notes).includes(num)),
      {
        notFound: `No tracker row links report #${num}. (Report IDs and tracker row IDs differ — ` +
          'use --row N to select by tracker #.)',
        ambiguous: (count, listing) =>
          `Report #${num} is linked by ${count} tracker rows — pass --role to disambiguate:\n${listing}`,
      },
    );
  }

  // --row N and a bare numeric selector both match the # column; they differ
  // only in whether the mismatch guard below treats the number as ambiguous.
  if (flags.row !== null || isBareNumericSelector) {
    const num = parseInt(flags.row !== null ? flags.row : selector, 10);
    return resolveCandidates(
      rows.filter(r => r.num === num),
      {
        notFound: `No tracker row with #${num}`,
        // #1704: a stale tracker # reused across 2+ rows means "the first
        // match" is a silent coin flip on which company gets edited. Refuse to
        // guess; require --role or the company selector instead.
        ambiguous: (count, listing) =>
          `#${num} is a duplicate tracker number shared by ${count} rows (see #1704) — ` +
          `pass --role to disambiguate, or use the company name instead:\n${listing}`,
      },
    );
  }

  const key = normalizeCompany(selector);
  if (!key) failUsage(`Selector "${selector}" is empty after normalization`);
  // Exact key first. A legal suffix (Inc, LLC) is a different key, so fall
  // back to the same corporate-form rule outcome and dedup already use.
  // Only when nothing matched exactly. Two hits stay ambiguous.
  let matches = rows.filter(r => normalizeCompany(r.company) === key);
  if (matches.length === 0) {
    matches = rows.filter(r => companiesMatchIgnoringCorporateForm(selector, r.company));
  }
  return resolveCandidates(
    matches,
    {
      notFound: `No tracker row with company matching "${selector}"`,
      ambiguous: (count, listing) =>
        `Company "${selector}" matches ${count} rows — pass the # or narrow with --role:\n${listing}`,
    },
  );
}

// ── locked read-modify-write ─────────────────────────────────────

// Shared with mark-pdf-ready.mjs (tracker-utils.mjs): dry-run never writes,
// so it must not hold the exclusive lock — a read-only preview should not
// block (or be blocked by) merge-tracker or another writer.
const lock = await acquireTrackerLockForCli(APPS_FILE, { dryRun: flags.dryRun, failWith });

let content;
try {
  content = readFileSync(APPS_FILE, 'utf-8');
} catch (err) {
  failWith(EXIT_NOT_FOUND, 'read-failure', `Cannot read tracker at ${APPS_FILE}: ${err.message}`);
}
// Guard the whole file, not just the selected row: reply-watch also checks
// receipt notes on other rows before confirming a proposal. A write anywhere
// between that check and acquiring this lock invalidates the reviewed snapshot.
if (flags.expectTracker !== null
    && createHash('sha256').update(content, 'utf8').digest('hex') !== flags.expectTracker) {
  failWith(EXIT_AMBIGUOUS, 'tracker-changed', 'Tracker changed since review; review the current tracker before retrying');
}
const lines = content.split('\n');
const parseOptions = { allowTabs: true, allowIndentation: true };
const colmap = resolveColumns(lines, parseOptions);

const rows = [];
for (let i = 0; i < lines.length; i++) {
  const row = parseTrackerRow(lines[i], colmap, parseOptions);
  if (row) rows.push({ ...row, lineIdx: i });
  else if (flags.reportLink !== null && colmap.report != null) {
    const report = splitTrackerCells(lines[i])[colmap.report] ?? '';
    if (parseMarkdownLinks(String(report)).some(link => link.label === flags.reportLink)) {
      failWith(EXIT_AMBIGUOUS, 'malformed-row', `Tracker row linking report #${flags.reportLink} has missing cells`);
    }
  }
}
if (rows.length === 0) {
  failWith(EXIT_NOT_FOUND, 'empty-tracker', `Tracker at ${APPS_FILE} has no data rows`);
}

const target = resolveRow(rows);

// A BARE numeric selector is often copied from a report filename. If the row ID
// disagrees with its local report link, silently updating that row can affect
// the wrong application. Company selectors remain usable, and --force records an
// explicit decision to proceed despite the mismatch.
//
// --row/--report are exempt by construction, not by override: the caller has
// already said which number space they mean, so there is no ambiguity left to
// guard. That distinction is what keeps the check meaningful — on a tracker
// whose counters have diverged, a guard that fires on every numeric call just
// teaches callers to pass --force, which disables it everywhere including the
// cases it was written for.
if (isBareNumericSelector && !flags.force) {
  const reportNums = extractTrackerReportNumbers(target.report, target.notes);
  const mismatched = reportNums.filter(num => num !== target.num);
  if (mismatched.length > 0) {
    failWith(
      EXIT_AMBIGUOUS,
      'report-number-mismatch',
      `Tracker #${target.num} points to report ID(s) ${reportNums.map(num => `#${num}`).join(', ')}. ` +
        `Say which you meant: --row ${target.num} (tracker row) or ` +
        `--report ${reportNums[0]} (report ID). ` +
        'The company selector also works; --force overrides the check instead of answering it.',
      { trackerNum: target.num, reportNums },
    );
  }

  // The check above compares the matched row's report link against its own #.
  // A backfilled row (#1799) has no link, so reportNums is empty, `mismatched`
  // is empty, and the check passes with nothing compared — while a DIFFERENT
  // row may link exactly this number as its report.
  //
  // That combination is not hypothetical: it is what merge-tracker.mjs's
  // "Tracker #N already used; assigning #M" fallback produces. The backfilled
  // row occupying #N is what pushes the evaluated row to #M, so the row a stale
  // numeric selector lands on is precisely the report-less one this check could
  // not see. Bare "#N" then names two applications at once and must not write.
  if (reportNums.length === 0) {
    const num = parseInt(selector, 10);
    const linkers = rows.filter(r => r !== target && extractTrackerReportNumbers(r.report, r.notes).includes(num));
    if (linkers.length > 0) {
      const listing = linkers.map(r => `#${r.num}\t${r.company}\t${r.role}`).join('\n');
      failWith(
        EXIT_AMBIGUOUS,
        'report-number-ambiguous',
        `"${num}" is ambiguous: tracker row #${num} (${target.company} — ${target.role}) has no report, ` +
          `but report #${num} is linked by:\n${listing}\n` +
          `Say which you meant: --row ${num} (the row) or --report ${num} (the report).`,
        { trackerNum: target.num, reportNum: num, linkedBy: linkers.map(r => ({ num: r.num, company: r.company, role: r.role })) },
      );
    }
  }
}

// --role is an explicit statement of which opening the caller means, but
// resolveRow only consults it to break ties between 2+ candidates. A selector
// matching exactly one row therefore returned that row without ever checking
// it against --role, silently rewriting a status the caller never asked for.
// That is the wrong-row mutation in #2009: the intended requisition may not be
// in the tracker at all (fuzzy-deduped away, or never merged), so the lone
// survivor for that company absorbs the update instead. Fail closed and let
// --force record an explicit decision, matching the report-mismatch guard.
// Exact-title equality must be checked separately: roleFuzzyMatch is a DEDUP
// predicate, and it deliberately returns false for two titles whose overlap is
// entirely baseline vocabulary (["platform","engineer"]) so that same-titled
// sibling reqs never auto-merge. That makes it unusable on its own here — it
// would reject --role "Platform Engineer" against a row that IS exactly that.
// The collapse must drop PUNCTUATION, never letters. `[^a-z0-9]` dropped every
// letter outside the Latin range, so any title written entirely in Japanese,
// Arabic or Cyrillic keyed to '' — two different titles then compared equal
// ('' === '') and the guard wrote the status to a row it had never actually
// matched (#2670). normalizeTextKey is the Unicode-aware normalizer company
// matching already used; it also folds NFKC, so a decomposed title still
// matches its composed row.
const normalizeRoleText = s => normalizeTextKey(
  String(s ?? '')
    // NFKC first: normalizeTextKey folds it too, but only AFTER this pre-map, so
    // a fullwidth ＃/＋＋ would reach the collapse unrecognized and be stripped as
    // punctuation — "C＃ Engineer" and "C＋＋ Engineer" both keying to
    // "c engineer". Fullwidth forms are ordinary Japanese typography, so this is
    // the same shipped-market surface as the rest of #2670. Folding here also
    // makes the ASCII and fullwidth spellings of one title match each other.
    .normalize('NFKC')
    // Preserve symbols that distinguish real titles before collapsing generic
    // punctuation — otherwise "C# Engineer" and "C++ Engineer" both fold to
    // "c engineer" and the exact-equality path treats them as the same row.
    .replace(/\+\+/g, ' plusplus ')
    .replace(/#/g, ' sharp '),
  ' ',
);
const roleMatchesTarget = normalizeRoleText(target.role) === normalizeRoleText(flags.role)
  || roleFuzzyMatch(target.role, flags.role);

if (flags.role && !flags.force && !roleMatchesTarget) {
  failWith(
    EXIT_AMBIGUOUS,
    'role-mismatch',
    `Tracker #${target.num} (${target.company}) is "${target.role}", which does not match --role "${flags.role}". ` +
      'The row you meant may not be in the tracker. Re-run with --force to update this row anyway.',
    { trackerNum: target.num, rowRole: target.role, requestedRole: flags.role },
  );
}
const oldStatus = target.status;
// A status outside states.yml (a hand-typed legacy value) is compared as
// written rather than refused, so the caller still gets "status changed" and
// not a usage error for a row it was right to show.
const statusKey = value => resolveCanonicalState(value, states) ?? String(value ?? '').trim();
// The ledger takes a canonical state or "-", and a row with anything else is
// dropped by its readers. A legacy cell (`Applied 2026-01-02`) is a known state
// once its date is off; copied raw, the change was lost to the funnel and to
// --undo. dedup-tracker.mjs logs its promotions the same way.
const ledgerState = value => resolveCanonicalState(stripStatusDecoration(value), states) ?? '-';

// The change --undo takes back is the one a retraction line would pop: the
// last surviving entry of this row's ledger replay. Read under the lock, so no
// writer can append between this read and the retraction below.
let undone = null;
if (flags.undo) {
  let ledger = '';
  try {
    ledger = readFileSync(statusLogPath(APPS_FILE), 'utf-8');
  } catch (err) {
    if (err.code !== 'ENOENT') failWith(EXIT_USAGE, 'read-failure', `Cannot read status log: ${err.message}`);
  }
  undone = replayObservations(parseStatusLog(ledger, states).observations).get(target.num)?.at(-1) ?? null;
  if (!undone) {
    failWith(EXIT_NOT_FOUND, 'nothing-to-undo', `#${target.num} has no logged status change to undo`);
  }
  if (statusKey(oldStatus) !== undone.to) {
    failWith(EXIT_AMBIGUOUS, 'undo-stale',
      `#${target.num} is ${oldStatus}, but its last logged change was to ${undone.to}. Set the status you want instead.`,
      { currentStatus: oldStatus, lastLogged: undone.to });
  }
  if (!undone.from) {
    failWith(EXIT_USAGE, 'undo-unknown-prior',
      `#${target.num}'s last logged change (to ${undone.to}) has no recorded prior status. Set the status you want instead.`);
  }
}
const newStatus = undone ? undone.from : requestedStatus;
if (flags.reportLink !== null && !resolveCanonicalState(oldStatus, states)) {
  failWith(EXIT_USAGE, 'invalid-current-state', `Tracker #${target.num} has an unrecognized current status: "${oldStatus}"`);
}
// A caller that asked a human first (reply-watch) holds a snapshot of the row
// it showed. The row can be replaced or edited while the prompt is open, and
// the yes belongs to the application on screen, not to a reusable row number.
// Unlike --expect-tracker, these look at the selected row only, so a write to
// an unrelated row in the meantime does not void the answer.
// Identity first: an edited row is refused even when it already carries the
// new status, because the consent was never about that row.
if (flags.expectRow !== null && trackerRowIdentity(target) !== flags.expectRow) {
  failWith(EXIT_AMBIGUOUS, 'row-changed', `Tracker #${target.num} changed since review; review it again before retrying`);
}
if (flags.expectStatus !== null && statusKey(oldStatus) !== newStatus
    && statusKey(oldStatus) !== statusKey(flags.expectStatus)) {
  failWith(EXIT_AMBIGUOUS, 'status-changed',
    `Tracker #${target.num} is now ${oldStatus}, not ${flags.expectStatus}; review it again before retrying`,
    { currentStatus: oldStatus });
}
const rawLine = lines[target.lineIdx];
const separator = trackerRowSeparator(rawLine);
// A tab is a cell delimiter in a legacy TSV row. Neutralize tabs only there;
// in a pipe table they remain ordinary note text.
const note = flags.note != null
  ? cell(separator === '\t' ? flags.note.replace(/\t/g, ' ') : flags.note)
  : null;

// ── advisory session-activity claim (#4532) ──────────────────────
//
// Concurrent sessions have no mutual awareness today: two sessions can each
// pick up the same tracker row and do redundant or conflicting work, with the
// collision only surfacing after the fact (#4506/#4507 — two sessions each
// wrote a batch/tracker-additions/*.tsv for the same report under a
// differently spelled company name). session-activity.mjs is a purely
// advisory signal modeled on reserve-report-num.mjs's sentinel pattern: it
// never blocks or changes the exit code, it only lets this run warn when
// another session already claimed the same row.
//
// The claim and its keying live in lib/status-hooks.mjs, so a writer that
// commits a status inside its own transaction takes the same one. Skipped
// entirely on --dry-run, matching the JD-archive-style triggers elsewhere in
// this file: a preview claims nothing.
const releaseActivityClaim = flags.dryRun ? () => {} : claimStatusActivity(target, `set-status → ${newStatus}`);

let statusChanged = false;
let noteChanged = false;
let statusLogged = false;
let statusLogRepaired = false;
let statusLogRepair = null;
const replacedNote = flags.replaceNote !== null ? cell(flags.replaceNote) : null;
try {
  // Rebuild only the matched line: change the Status cell, append the note, keep
  // every other cell exactly as parsed.
  const parts = splitTrackerCells(rawLine);
  while (parts.length <= Math.max(colmap.status, colmap.notes ?? 0)) parts.push('');

  const replaceCellValue = (index, value) => {
    const original = parts[index] ?? '';
    const trimmed = original.trim();
    if (trimmed) {
      const start = original.indexOf(trimmed);
      parts[index] = original.slice(0, start) + value + original.slice(start + trimmed.length);
    } else if (original.length >= 2) {
      const half = Math.floor(original.length / 2);
      parts[index] = original.slice(0, half) + value + original.slice(half);
    } else {
      parts[index] = ` ${value} `;
    }
  };

  statusChanged = parts[colmap.status].trim() !== newStatus;
  if (statusChanged) replaceCellValue(colmap.status, newStatus);

  // Text after a date in the old cell is no part of any state, and replacing the
  // cell would lose it. It moves to Notes, as normalize-statuses.mjs moves it,
  // unless a whole Notes entry already holds it.
  if (statusChanged && colmap.notes != null && statusTextAfterDate(oldStatus)) {
    const kept = (parts[colmap.notes] ?? '').trim();
    const moved = oldStatus.trim();
    if (!hasNoteEntry(kept, moved)) replaceCellValue(colmap.notes, prependNote(kept, moved));
  }

  if (note) {
    if (colmap.notes == null) {
      failWith(EXIT_USAGE, 'no-notes-column', 'Tracker has no Notes column — cannot apply --note');
    }
    const existing = (parts[colmap.notes] ?? '').trim();
    if (replacedNote !== null) {
      // Use the same whole-note boundaries as append idempotency. Prefer the
      // longer complete span so NEW containing OLD (including "; ") is not
      // expanded again on retry, and OLD containing NEW is still replaced.
      const alternatives = [note, replacedNote].sort((a, b) => b.length - a.length)
        .map(text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
      const wholeNotes = new RegExp(`(^|; )(${alternatives.join('|')})(?=; |$)`, 'g');
      let found = false;
      const updated = existing.replace(wholeNotes, (_match, prefix, entry) => {
        found = true;
        return prefix + (entry === replacedNote ? note : entry);
      });
      if (!found) {
        failWith(EXIT_USAGE, 'replace-note-not-found', 'Neither --replace-note nor --note matches a whole note in the Notes cell');
      }
      replaceCellValue(colmap.notes, updated);
      noteChanged = updated !== existing;
    } else {
      // Delimiter-aware idempotency: the note counts as already present only when
      // it appears as a whole "; "-delimited entry (or as the entire field) — a
      // bare substring of a longer entry ("sent" inside "sent CV") must not
      // suppress a genuinely new note. Matching the full note text at entry
      // boundaries (instead of splitting the field into segments) keeps retries
      // idempotent even when the note itself contains "; ".
      if (!hasNoteEntry(existing, note)) {
        replaceCellValue(colmap.notes, existing && existing !== '—' && existing !== '-' ? `${existing}; ${note}` : note);
        noteChanged = true;
      }
    }
  }

  if ((statusChanged || noteChanged) && !flags.dryRun) {
    if (separator === '\t') {
      const closing = rawLine.trimEnd().endsWith('|');
      lines[target.lineIdx] = parts[0] + '|' + parts.slice(1, closing ? -1 : undefined).join('\t')
        + (closing ? '|' + parts.at(-1) : '');
    } else {
      lines[target.lineIdx] = parts.join('|');
    }
    try {
      writeFileAtomic(APPS_FILE, lines.join('\n'));
    } catch (err) {
      // Same structured error contract as every other failure path — a raw
      // stack trace on stdout/stderr would break --json consumers.
      failWith(EXIT_USAGE, 'write-failure', `Cannot write tracker at ${APPS_FILE}: ${err.message}`);
    }
  }

  // ── status-log append (transition ledger, read by funnel-velocity.mjs) ──
  // Observation trail only: the tracker stays the source of truth for STATE,
  // the ledger records WHEN transitions happened. A failed append is a warning,
  // never a failure — the status write above already succeeded. Sibling of the
  // tracker file so CAREER_OPS_TRACKER redirects (tests, custom layouts) keep
  // the ledger next to the tracker it describes. Inside the lock window, so
  // concurrent writers can't interleave lines.
  // An undo retracts the entry it selected even when that entry left the
  // status as it was (Applied → Applied), or the next undo would pick it again.
  // The retraction is the undo, so a failed append puts the old status back.
  if (undone && !flags.dryRun) {
    statusLogged = appendStatusTransition(APPS_FILE, {
      num: target.num,
      date: localToday(),
      from: '-',
      to: '-',
      source: flags.source ?? 'set-status',
      note: `undo ${undone.from} → ${undone.to}`,
    });
    if (!statusLogged) {
      let restored = !statusChanged;
      if (statusChanged) {
        lines[target.lineIdx] = rawLine;
        try {
          writeFileAtomic(APPS_FILE, lines.join('\n'));
          restored = true;
        } catch { /* reported below */ }
      }
      failWith(EXIT_USAGE, 'undo-not-logged', restored
        ? `Could not log the undo for #${target.num}, so it stays ${oldStatus}`
        : `Could not log the undo for #${target.num}, and could not put it back to ${oldStatus}; it now reads ${newStatus}`);
    }
  } else if (statusChanged && !flags.dryRun) {
    // LOCAL today: the UTC day is TOMORROW for a west-of-Greenwich evening run,
    // so this appended a status-log row dated a day that had not happened yet
    // (#2932, mirroring #2765). status-log.tsv is what funnel-velocity reads for
    // time-between-stages, so a future-dated transition skews the interval it
    // measures rather than just looking odd in the file.
    statusLogged = appendStatusTransition(APPS_FILE, {
      num: target.num,
      date: flags.on ?? localToday(),
      from: ledgerState(oldStatus),
      to: newStatus,
      source: flags.source ?? 'set-status',
    });
  }
  // A dashboard call that received the partial-success error above can retry
  // the same Applied action. The tracker is already Applied, so there is no
  // normal transition to log; append one correction observation only when the
  // effective timeline does not already end at Applied. This is append-only
  // and idempotent, and the correction source is folded by funnel-velocity.mjs
  // onto the repaired stage.
  if (flags.repairStatusLog && !statusChanged && newStatus === 'Applied' && !flags.dryRun) {
    const logPath = statusLogPath(APPS_FILE);
    const timeline = [];
    let inspectionError = null;
    try {
      const log = readFileSync(logPath, 'utf-8');
      for (const line of log.split(/\r?\n/)) {
        const cells = line.trimEnd().split('\t');
        if (cells[0] !== String(target.num) || cells.length < 5) continue;
        const to = cells[3];
        const source = cells[4];
        if (to === '-') {
          timeline.pop();
        } else if (source === 'correction') {
          const index = timeline.map(entry => entry.to).lastIndexOf(to);
          if (index >= 0) timeline[index] = { to, date: cells[1] };
          else timeline.push({ to, date: cells[1] });
        } else {
          timeline.push({ to, date: cells[1] });
        }
      }
    } catch (err) {
      if (err.code !== 'ENOENT') inspectionError = err;
    }
    if (inspectionError) {
      const error = `status-log inspection failed: ${inspectionError.message}`;
      statusLogRepair = { attempted: true, repaired: false, error };
      console.error(`⚠ ${error}`);
    } else if (timeline.at(-1)?.to === 'Applied') {
      statusLogRepair = { attempted: true, repaired: false, reason: 'already-present' };
    } else if (timeline.length === 0) {
      // No earlier ledger entry for this row: nothing proves a transition was
      // lost, so do not invent history from the tracker date alone.
      statusLogRepair = { attempted: true, repaired: false, reason: 'no-history' };
    } else {
      // Prefer an explicit event date, then the latest effective ledger date,
      // then the tracker's own dated row. Never invent today's date for an
      // existing Applied row whose history is older or absent.
      const eventDate = flags.on ?? timeline.at(-1).date;
      if (!eventDate) {
        const error = 'status-log repair needs an event date (--on or a dated tracker row)';
        statusLogRepair = { attempted: true, repaired: false, error };
        console.error(`⚠ ${error}`);
      } else {
        try {
          appendLedgerRows(logPath, `${target.num}\t${eventDate}\t-\tApplied\tcorrection\t\n`);
          statusLogged = true;
          statusLogRepaired = true;
          statusLogRepair = { attempted: true, repaired: true };
        } catch (err) {
          const error = `status-log repair failed: ${err.message}`;
          statusLogRepair = { attempted: true, repaired: false, error };
          console.error(`⚠ ${error}`);
        }
      }
    }
  }
} finally {
  lock?.release();
  // Release the claim once the write (and its log append) has finished, so
  // it never outlives the run — reached even if something above threw.
  releaseActivityClaim();
}

const changed = statusChanged || noteChanged;

// ── follow-up seeding (#1430) ────────────────────────────────────
//
// The transition into Applied is where the first follow-up gets scheduled.
// set-status.mjs used to only ANNOUNCE that — `followupSeedCandidate: true` —
// and nothing consumed the flag: the only callers of followup-seed.mjs were
// modes/apply.md and modes/followup.md, both agent instructions. So recording
// an application from the web UI, or from this CLI directly, wrote the tracker
// and the ledger correctly and scheduled nothing, silently (#3459).
//
// Seeding HERE rather than in each caller is what makes that one fix instead of
// three: #2901 converged /api/status onto this script, so the web path inherits
// it, and so does every future caller that delegates here rather than editing
// the table.
//
// AFTER the tracker lock is released, deliberately: the seeder re-reads the
// row this run just wrote (lib/status-hooks.mjs has the rest of the why).
//
// A seeding failure NEVER fails the status change. The write has already
// committed and the caller's exit code is about that write — same policy as
// the status-log append above.
let followupSeeded = null;
if (!undone && (statusChanged || flags.repairFollowup) && newStatus === 'Applied') {
  followupSeeded = await seedFollowupOnApplied(target.num, {
    trackerPath: APPS_FILE,
    // --on is the day the user says the application was sent. Without it,
    // a fresh transition passes today as the status-change date, which
    // resolveAppliedDate ranks below an "Applied YYYY-MM-DD" in the notes and
    // above the evaluation-date column. A repair retry passes neither,
    // because the apply happened on an earlier run.
    date: flags.on,
    statusChangeDate: statusChanged ? localToday() : undefined,
    dryRun: flags.dryRun,
    quiet: flags.json,
  });
}

// ── JD archive trigger on Interview (#4506-direction-2) ─────────────
//
// The last reliable moment the posting is still likely live
// (lib/status-hooks.mjs has the full reasoning). Same policy as the follow-up
// seeding above: never fails the status change, never re-archives on an
// idempotent re-run into an already-Interview row (statusChanged gates that),
// and does nothing on a dry run.
let jdArchiveTriggered = null;
if (!undone && statusChanged && newStatus === 'Interview' && !flags.dryRun) {
  jdArchiveTriggered = archiveJdOnInterview(target, {
    trackerPath: APPS_FILE,
    detach: flags.detachJdArchive,
    json: flags.json,
  });
}

// ── report ───────────────────────────────────────────────────────

const result = {
  changed,
  num: target.num,
  company: target.company,
  role: target.role,
  oldStatus,
  newStatus,
  ...(note != null ? { note } : {}),
  ...(replacedNote !== null ? { replacedNote } : {}),
  ...(flags.dryRun ? { dryRun: true } : {}),
  // Fire the #1430 hook on an actual transition INTO Applied or an explicit
  // lifecycle repair retry. The seeder itself is idempotent, so a repair retry
  // cannot stack duplicate follow-ups.
  // followupSeedCandidate is kept for any consumer already reading it; the
  // seeding it used to merely advertise now actually happens, and its outcome
  // travels beside it.
  ...(undone ? { undone: { from: undone.from, to: undone.to, date: undone.date } } : {}),
  ...(!undone && statusChanged && newStatus === 'Applied' ? { followupSeedCandidate: true } : {}),
  ...(followupSeeded ? { followupSeeded } : {}),
  ...(jdArchiveTriggered ? { jdArchiveTriggered } : {}),
  ...(statusChanged && !flags.dryRun ? { statusLogged } : {}),
  ...(statusLogRepaired ? { statusLogRepaired } : {}),
  ...(statusLogRepair ? { statusLogRepair } : {}),
  tracker: APPS_FILE,
};

const oldLabel = resolveCanonicalState(oldStatus, states);
if (!undone && statusChanged && !flags.dryRun && states.find(s => s.label === oldLabel)?.terminal) {
  console.warn(`⚠ #${target.num} was ${oldLabel}, a terminal state. Reopened as ${newStatus}.`);
}

if (flags.json) {
  // JSON must be the last thing written to stdout; machine callers parse stdout as one JSON document.
  console.log(JSON.stringify(result, null, 2));
} else {
  const verb = undone ? (flags.dryRun ? 'would undo' : 'undid') : flags.dryRun ? 'would set' : changed ? 'set' : 'already';
  console.log(`✅ #${target.num} ${target.company} — ${target.role}: ${verb} ${oldStatus} → ${newStatus}${note ? ` (note: ${note})` : ''}`);
  // Only when seeding did NOT happen. The advisory predates the seeding above
  // and asked the user to do by hand what now runs for them; leaving it
  // unconditional would read as a contradiction right under "Follow-up seeded".
  if (!undone && statusChanged && !flags.dryRun && newStatus === 'Applied' && !followupSeeded?.seeded && followupSeeded?.reason !== 'disabled') {
    console.error('ℹ️  Status is Applied — consider seeding follow-ups in data/follow-ups.md (#1430: node followup-cadence.mjs)');
  }
}
process.exit(EXIT_OK);