honestweek 0.2.0 → 0.3.0

package/lib/view.mjs

@@ -8,34 +8,37 @@
 // file is deleted once the page has traded its code for the run's key, after
 // OPENER_TTL_MS when it hasn't (its code stops working then too), and on exit.
 //
-// Nothing is published and nothing it reads is written to disk. With --demo it builds
+// Nothing is published, and it keeps only what the user chooses to save (the config, Run with
+// Codex's answers). With --demo it builds
 // the made-up demo week in a temporary folder, serves only that, and deletes it on exit.
 
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 
-import { HISTORY_LIMIT_MB, hostTimezone, loadConfig } from './config.mjs';
+import { hostTimezone } from './config.mjs';
+import { findConfig, lookupUserConfig, noteConfig } from './config-lookup.mjs';
 import { currentCommand, pageCommand } from './invocation.mjs';
 import { buildDemoWeek, markDemoOwner, sweepStaleDemoDirs } from './demo/week.mjs';
 import { defaultOpener } from './preview.mjs';
-import { normalizeGoalRecord } from './replay/goals.mjs';
 import { defaultRoots } from './replay/sources.mjs';
-import { localDateInTimezone } from './resolve-week.mjs';
 import { createViewData, privateWordCount, privateWordsNote } from './view/data.mjs';
 import { CODE_TTL_MS, startViewServer } from './view/server.mjs';
 import { createSetup } from './view/setup.mjs';
 import { createInsights, insightsDir } from './view/insights.mjs';
+import { pageLink } from './view/page-link.mjs';
 import { createCodexJudge } from './view/codex-judge.mjs';
 import { createSettings, saveInsightsFlag } from './view/settings.mjs';
-import { bytesIn, fitsInMemory, historyInfo, logFiles, memoryRoom, paramsOfHistory, planWindow, sizeText, WHOLE_DAYS, windowAnswer } from './view/window.mjs';
+import { bytesIn, fitsInMemory, historyInfo, logFiles, memoryRoom, paramsOfHistory, sizeText, WHOLE_DAYS, windowAnswer } from './view/window.mjs';
 import { createProgressiveData, fitWindow } from './view/progressive.mjs';
+import { createSaver } from './saved/saver.mjs';
+import { absolute, limitOf, ownWeek, readGoalList, resolveViewWindow, setup, SetupError, spanDays, validTimezone } from './view/own-week.mjs';
+import { DEMO_TERM } from './demo/week.mjs';
+
+export { DEMO_TERM, ownWeek, readGoalList, resolveViewWindow };
 
 const CONFIG_FILE = 'honestweek.config.json';
-const DEFAULT_DAYS = 7;
-/** The made-up project name the demo hides as a private word, so the switch shows something. */
-export const DEMO_TERM = 'lantern';
 /** Where --self-test serves its click-through page. */
 export const SELF_TEST_PAGE = 'selftest/clickthrough.html';
 /** The page a folder with no config opens on. */
@@ -48,23 +51,25 @@ export const OPENER_TTL_MS = 2 * 60 * 1000;
 export const HELP = `honestweek view: find, check and replay your agent work in your browser.
 
 Usage:
-  honestweek view [--days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>]
+  ${currentCommand()} view [--days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>]
                   [--goals <file>] [--config <file>] [--timezone <zone>]
                   [--port <n>] [--no-open] [--self-test]
-  honestweek view --demo [--port <n>] [--no-open] [--self-test]
+  ${currentCommand()} view --demo [--port <n>] [--no-open] [--self-test]
 
 Reads your config and the last 7 days of your Claude Code and Codex logs, then
-serves a page on 127.0.0.1 and opens your browser. With no
-honestweek.config.json in this folder, the page that opens is Setup: it finds
-your repositories, email and timezone, asks which names and client words to
-keep private, shows the config, and saves it, then goes on to your week. For
-scripts and CI, honestweek init asks the same questions in a terminal. With
+serves a page on 127.0.0.1 and opens your browser. The config is the
+honestweek.config.json in this folder, else the file HONESTWEEK_CONFIG names,
+else ~/.honestweek/honestweek.config.json. With none of those, the page that
+opens is Setup: it finds your repositories, email and timezone, asks which
+names and client words to keep private, shows the config, and saves it, in
+this folder or for every folder, then goes on to your week. For
+scripts and CI, ${currentCommand()} init asks the same questions in a terminal. With
 no --days, --from or --to, it reads as far back as the config's "history"
 says (Setup and the Settings page set it), or the last 7 days. Type a pull request, a commit,
 a file, a branch or some words to find the sessions and goals behind it, and
 replay any session step by step. Every step and link says how it's known:
 recorded, derived, inferred, missing, or ambiguous. Nothing is published, nothing
-leaves your machine, and nothing it reads is written to disk.
+leaves your machine, and you have full control over what it keeps.
 
 The page shows redacted text. Its Show private text switch shows names, client
 words and folders on your own screen; keys, tokens and passwords stay hidden.
@@ -74,7 +79,8 @@ config, so until you list some, they show as written, and view says so.
 Each run makes a fresh key. The address it opens and prints carries a one-time
 code instead, which the page trades for that key, so only a page you opened can
 read your data. A printed address works once, within ${CODE_TTL_MS / 60_000} minutes. Press Enter
-here to print a fresh address. Ctrl+C stops it.
+here to print a fresh address, or type link and a page, such as
+link replay.html?session=<id>, for a fresh one-time address to that page. Ctrl+C stops it.
 
 Options:
       --days <n>           Look at the last n days (default 7).
@@ -84,9 +90,13 @@ Options:
                            config's week.timezone).
       --goals <file>       Your goal list: a JSON file of goals and their changes.
                            You can set "goalsFile" in the config instead.
-      --config <file>      Read this config instead of ./honestweek.config.json.
+      --config <file>      Read this config instead of the one honestweek finds.
       --port <n>           Serve on this port (default: a free one).
       --no-open            Don't open a browser; just print the address.
+      --page <page>        Open on this page instead of Problems, for example
+                           "replay.html?session=<id>" or one step of it,
+                           "replay.html?session=<id>#<thread>~<step>". Only view's
+                           own pages are accepted.
       --demo               Look around a made-up week instead of your own logs. It
                            uses its own logs, config, goal list and week, so it
                            can't be combined with --config, --goals, --days,
@@ -98,17 +108,14 @@ Options:
   -h, --help               Show this help.
 `;
 
-const VALUED = new Set(['--config', '--days', '--from', '--to', '--timezone', '--goals', '--port']);
+const VALUED = new Set(['--config', '--days', '--from', '--to', '--timezone', '--goals', '--port', '--page']);
 const BARE = new Set(['--no-open', '--demo', '--self-test', '--help', '-h']);
 const DEMO_REFUSES = ['--config', '--goals', '--days', '--from', '--to', '--timezone'];
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
 function defaultIo() {
   return { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) };
 }
 
-class SetupError extends Error {}
-const setup = (message) => new SetupError(message);
 
 /** Parse argv into { flags, values }; an unknown option or a missing value throws. */
 export function parseViewArgs(argv) {
@@ -140,97 +147,6 @@ export function parseViewPort(value) {
   return Number(value);
 }
 
-const validDate = (s) => DATE_RE.test(s) && !Number.isNaN(Date.parse(`${s}T00:00:00Z`)) && new Date(`${s}T00:00:00Z`).toISOString().slice(0, 10) === s;
-const spanDays = (a, b) => Math.round((Date.parse(`${b}T00:00:00Z`) - Date.parse(`${a}T00:00:00Z`)) / 86400000) + 1;
-const shiftDay = (day, n) => new Date(Date.parse(`${day}T00:00:00Z`) + n * 86400000).toISOString().slice(0, 10);
-
-function validTimezone(tz) {
-  try {
-    new Intl.DateTimeFormat('en-US', { timeZone: tz });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** The window to read: --from/--to, or the last --days days (default 7) ending today. */
-export function resolveViewWindow(values, timezone, now = Date.now()) {
-  const hasRange = '--from' in values || '--to' in values;
-  if (hasRange && '--days' in values) throw setup('view: use --days, or --from with --to, not both.');
-  if (hasRange) {
-    const from = values['--from'];
-    const to = values['--to'];
-    if (from === undefined || to === undefined) throw setup('view: --from and --to go together. Give both, or use --days.');
-    for (const [name, v] of [['--from', from], ['--to', to]]) if (!validDate(v)) throw setup(`view: ${name} must be a date written YYYY-MM-DD (got ${JSON.stringify(v)}).`);
-    if (from > to) throw setup(`view: --from (${from}) is after --to (${to}).`);
-    return { from, to };
-  }
-  let days = DEFAULT_DAYS;
-  if ('--days' in values) {
-    const v = values['--days'];
-    if (!/^\d{1,4}$/.test(v) || Number(v) < 1 || Number(v) > 3660) throw setup(`view: --days must be a whole number from 1 to 3660 (got ${JSON.stringify(v)}).`);
-    days = Number(v);
-  }
-  const today = localDateInTimezone(new Date(now), timezone).toISOString().slice(0, 10);
-  return { from: shiftDay(today, -(days - 1)), to: today };
-}
-
-/**
- * readGoalList(path) -> the parsed goal list. Throws a setup error with a plain message
- * when the file is missing, can't be read as JSON, is the goals page's registry, or doesn't fit.
- */
-export function readGoalList(path) {
-  if (!existsSync(path)) throw setup(`view: no goal list at ${path}. Fix the path, or leave the goal list out; search and replay work without one.`);
-  let parsed;
-  try {
-    parsed = JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    // Never the parser's message: it quotes the file's first characters, and this check takes
-    // any path. A folder or an unreadable file reads the same as a file that isn't JSON.
-    throw setup(`view: ${path} isn't a goal list (not valid JSON).`);
-  }
-  const looksLikeRegistry = parsed && typeof parsed === 'object' && !Array.isArray(parsed.goals) && (parsed.objectives !== undefined || parsed.projectToObjective !== undefined);
-  if (looksLikeRegistry) {
-    throw setup(`view: ${path} looks like the goals page's list (its "objectives"), which honestweek build reads. view reads a different file, a goal list: { "goals": [{ "id": "g-1", "title": "Ship the parser" }], "events": [] }. The README's goal list section shows the format.`);
-  }
-  try {
-    normalizeGoalRecord(parsed);
-  } catch (err) {
-    throw setup(`view: ${path} isn't a goal list: ${String(err?.message ?? err).replace(/^replay: /, '')}`);
-  }
-  return parsed;
-}
-
-/** The config's limit on log data a saved choice loads, in MB. */
-const limitOf = (config) => config?.historyLimitMB ?? HISTORY_LIMIT_MB.default;
-
-const absolute = (cwd, p) => (isAbsolute(p) ? p : resolve(cwd, p));
-
-/** The person's own week: the config, the window and the goal list the options and the config
- *  name. Throws a setup error with a plain message when one of them can't be read. */
-function ownWeek({ values, cwd, env, now }) {
-  const configPath = values['--config'] ? absolute(cwd, values['--config']) : join(cwd, CONFIG_FILE);
-  if (!existsSync(configPath)) throw setup(`view: no config at ${configPath}. Run ${currentCommand()} view in a folder with no config to set one up in your browser (or ${currentCommand()} init in a terminal), or ${currentCommand()} view --demo to look around a made-up week first.`);
-  let config;
-  try {
-    config = loadConfig(configPath);
-  } catch (err) {
-    throw setup(`view: ${err.message}`);
-  }
-  const timezone = values['--timezone'] ?? config.week?.timezone;
-  if (!validTimezone(timezone)) throw setup(`view: ${JSON.stringify(timezone)} isn't a timezone this machine knows. Use an IANA name such as Europe/Paris or UTC.`);
-  const roots = defaultRoots(env);
-  // The flags win for one run. With none, a saved choice is sized to fit (the last week, or up to
-  // 7 days, always whole); with no saved choice either, it's the last 7 days, as it always was.
-  // Either way a window of more than one day loads its newest day first.
-  const flagged = ['--days', '--from', '--to'].some((f) => f in values);
-  const plan = !flagged && config.history ? planWindow(config.history, { roots, timezone, now: now(), maxBytes: limitOf(config) * 1024 * 1024 }) : null;
-  const { from, to } = plan ?? resolveViewWindow(values, timezone, now());
-  const goalsPath = values['--goals'] ? absolute(cwd, values['--goals']) : config.goalsFile ?? null;
-  const goalRecord = goalsPath ? readGoalList(goalsPath) : null;
-  return { config, configPath, roots, from, to, timezone, goalRecord, windowNote: plan?.note ?? null };
-}
-
 /** What the data routes answer while setup isn't done: every page but Setup is sent there.
  *  `appeared()` answers the week's data once a config turns up in the folder, whoever wrote it
  *  (Setup, or init in another terminal), and null until then. */
@@ -295,6 +211,12 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   const demo = flags.has('--demo');
   const selfTest = flags.has('--self-test');
   const noOpen = flags.has('--no-open');
+  // --page: the page the opened and printed addresses go to, checked before anything is read.
+  const startAt = values['--page'] === undefined ? null : pageLink(values['--page']);
+  if (startAt?.error) {
+    io.err(`view: --page: ${startAt.error}\n`);
+    return 1;
+  }
 
   const cleanups = [];
   const cleanup = () => {
@@ -336,13 +258,14 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
         timezone: d.week.timezone,
         goalRecord: d.goalRecord,
       };
-    } else if (!values['--config'] && !existsSync(join(cwd, CONFIG_FILE))) {
+    } else if (findConfig({ cwd, flag: values['--config'] }).source === 'none') {
       // No config here: the Setup page writes one. The options that don't need a config are
       // checked now, so a typo shows before setup rather than after it.
       if ('--timezone' in values && !validTimezone(values['--timezone'])) throw setup(`view: ${JSON.stringify(values['--timezone'])} isn't a timezone this machine knows. Use an IANA name such as Europe/Paris or UTC.`);
       resolveViewWindow(values, values['--timezone'] ?? 'UTC', now());
       if (values['--goals']) readGoalList(absolute(cwd, values['--goals']));
     } else {
+      noteConfig(io.err, 'view', findConfig({ cwd, flag: values['--config'] }), { cwd, writes: true });
       setupData = ownWeek({ values, cwd, env, now });
     }
   } catch (err) {
@@ -355,9 +278,13 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   }
 
   const command = pageCommand(currentCommand());
-  // Settings can't change a config named with --config outside this folder; the /insights
-  // toggle follows the same rule, and is kept for this run only when it can't be saved.
-  const elsewhere = () => !!values['--config'] && resolve(absolute(cwd, values['--config'])) !== resolve(join(cwd, CONFIG_FILE));
+  // Settings changes the config this run reads, in its own folder, which may not be this one
+  // (--config, HONESTWEEK_CONFIG, the user-level file). It writes only a file called
+  // honestweek.config.json, so a config named with --config under another name stays as it is;
+  // the /insights toggle follows the same rule, and is kept for this run only when it can't be saved.
+  const configDir = () => (setupData?.configPath ? dirname(setupData.configPath) : cwd);
+  const fileName = (p) => (process.platform === 'win32' ? basename(p).toLowerCase() : basename(p));
+  const elsewhere = () => !!setupData?.configPath && fileName(setupData.configPath) !== CONFIG_FILE;
   // The Problems page's optional /insights group and its Run button: one for the whole run, so
   // a run still going survives a Settings save.
   const insights = createInsights({
@@ -368,9 +295,9 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
     cwd,
     persist: async (on) => {
       if (demo) return { remembered: false, note: 'For this run only: the demo has no config to save.' };
-      if (elsewhere()) return { remembered: false, note: 'For this run only: the config named with --config is outside this folder.' };
-      if (!existsSync(join(cwd, CONFIG_FILE))) throw new Error('finish setup first');
-      return saveInsightsFlag(cwd, on);
+      if (elsewhere()) return { remembered: false, note: `For this run only: the config named with --config isn't called ${CONFIG_FILE}, so it can't be changed here.` };
+      if (!existsSync(join(configDir(), CONFIG_FILE))) throw new Error('finish setup first');
+      return saveInsightsFlag(configDir(), on);
     },
   });
   cleanups.push(() => insights.stop());
@@ -379,6 +306,8 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   // It runs only while Include /insights is on, the switch the page shows its button under.
   const codexJudge = createCodexJudge({ configDir: () => (setupData?.configPath ? dirname(setupData.configPath) : null), demo, env, isOn: () => insights.isOn() });
   cleanups.push(() => codexJudge.stop());
+  // Saved results (lib/saved/): only with "saveResults" on, in a folder beside the config view read.
+  const saver = createSaver({ configDir: () => (setupData?.configPath ? dirname(setupData.configPath) : null), config: () => setupData?.config ?? null, demo, now });
   // Checks that keep a large window from running the process out of memory, and Show private
   // text's second copy only when it fits beside the first. The window before (for the Problems
   // page's trend) follows the window's own rule: for a week or less, all of it, newest day first,
@@ -386,7 +315,7 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   const guards = (d) => ({
     earlierProgressive: spanDays(d.from, d.to) <= WHOLE_DAYS,
     earlierCheck: (w) => {
-      const files = logFiles(d.roots, d.timezone);
+      const files = d.files ?? logFiles(d.roots, d.timezone);
       const bytes = bytesIn({ files, from: w.from, to: w.to });
       const limit = limitOf(d.config);
       if (spanDays(d.from, d.to) > WHOLE_DAYS && bytes > limit * 1024 * 1024) return { why: 'limit', note: `The ${w.days} days before hold ${sizeText(bytes)} of logs, past the ${limit} MB limit, so they aren't compared.` };
@@ -401,11 +330,11 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
     },
   });
   const weekData = (d) => {
-    const base = { ...d, demo, selfTest, now, command, insights, codexJudge, ...(buildHistory ? { buildHistory } : {}) };
+    const base = { ...d, demo, selfTest, now, command, insights, codexJudge, settingsOpen: !elsewhere(), ...(buildHistory ? { buildHistory } : {}), ...(d.config?.saveResults?.on === true ? { onChecked: saver.onChecked, savedLoad: (w) => saver.load({ ...w, roots: d.roots }), savedCounts: (w) => saver.counts({ ...w, roots: d.roots }) } : {}) };
     // The demo week is small and fixed, so it loads at once, as it always has.
     const made = demo
       ? createViewData(base)
-      : createProgressiveData({ from: d.from, to: d.to, timezone: d.timezone, roots: d.roots, make: (o) => createViewData({ ...base, ...o, ...guards({ ...d, from: o.from, to: o.to }) }) });
+      : createProgressiveData({ from: d.from, to: d.to, timezone: d.timezone, roots: d.roots, ...(d.files ? { files: d.files } : {}), make: (o) => createViewData({ ...base, ...o, ...guards({ ...d, from: o.from, to: o.to }) }) });
     made.start();
     return made;
   };
@@ -416,7 +345,7 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   let data = setupData
     ? weekData(setupData)
     : setupPendingData(command, async () => {
-        if (!existsSync(join(cwd, CONFIG_FILE))) return null;
+        if (findConfig({ cwd, flag: values['--config'] }).source === 'none') return null;
         await adopt().catch(() => {});
         return data;
       });
@@ -449,24 +378,27 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
     return { next: 'problems.html' };
   };
   // Setup mode: the Setup page writes the config with init's functions, then the week loads.
-  const setupFlow = setupData ? null : createSetup({ cwd, command, inferEmail, checkGoals: readGoalList, history: logs, onSaved: adopt });
-  // Settings changes this folder's config later. It's closed for the demo, during setup, and
-  // for a config named with --config, which may sit outside the folder view started in.
+  // It can save for every folder when this run would read the user-level file.
+  const setupFlow = setupData ? null : createSetup({ cwd, command, inferEmail, checkGoals: readGoalList, history: logs, onSaved: adopt, userConfig: lookupUserConfig(), configFound: () => findConfig({ cwd, flag: values['--config'] }).source !== 'none' });
+  // Settings changes the config later. It's closed for the demo, during setup, and for a config
+  // named with --config under another name.
   const settingsFlow = demo
     ? null
     : createSettings({
         cwd,
+        configDir,
         checkGoals: readGoalList,
         history: logs,
         windowFor: (h, limit) => planner(paramsOfHistory(h, limit)).body,
         onSaved: reload,
+        saved: () => saver.info(),
         editable: () => {
           if (setupFlow?.pending()) return 'Finish setup first.';
-          if (elsewhere()) return `This run reads a config named with --config, so Settings can't change it here. Run view in that config's folder without --config.`;
+          if (elsewhere()) return `This run reads a config named with --config that isn't called ${CONFIG_FILE}, so Settings can't change it here.`;
           return null;
         },
       });
-  const homePage = () => (setupFlow?.pending() ? SETUP_PAGE : '');
+  const homePage = () => (setupFlow?.pending() ? SETUP_PAGE : (startAt?.page ?? ''));
 
   let openerDir = null;
   const removeOpener = () => {
@@ -478,9 +410,12 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
       ['/api/insights/toggle', (body) => insights.toggle(body)],
       ['/api/insights/run', () => insights.run()],
       ['/api/insights/codex-run', () => codexJudge.run(data.codexWork?.() ?? null)],
+      ['/api/saved/forget', () => saver.forget()],
     ]);
     handle = await startViewServer({ data, setup: setupFlow, settings: settingsFlow, planner: demo ? null : planner, actions, port, selfTest, onClaim: (purpose) => purpose === 'opener' && removeOpener(), ...(codeClock ? { now: codeClock } : {}) });
   } catch (err) {
+    // The week's build has already started: it stops too, so a run that ends here reads no git.
+    data.stop?.();
     cleanup();
     io.err(err?.code === 'EADDRINUSE' ? `view: port ${port} is already in use. Leave --port out to pick a free one, or choose another.\n` : `view: couldn't start the page server (${err?.message ?? err}).\n`);
     return 1;
@@ -491,6 +426,8 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   const stop = async () => {
     if (stopped) return;
     stopped = true;
+    // A build still reading stops too, so a stopped page runs no more git.
+    data.stop?.();
     await handle.close();
     cleanup();
   };
@@ -517,7 +454,7 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   if (setupFlow) io.out(`honestweek view: there's no ${CONFIG_FILE} in ${cwd}, so setup is open in your browser at ${handle.url} (Ctrl+C stops it). For scripts and CI, ${currentCommand()} init still works.\n`);
   else io.out(`honestweek view: serving ${demo ? 'the made-up demo week' : `${setupData.from} to ${setupData.to}`} at ${handle.url} (Ctrl+C stops it).\n`);
   if (setupData?.windowNote) io.out(`${setupData.windowNote}\n`);
-  if (!demo && setupData && privateWordCount(setupData.config) === 0) io.out(`${privateWordsNote(currentCommand())}\n`);
+  if (!demo && setupData && privateWordCount(setupData.config) === 0) io.out(`${privateWordsNote(currentCommand(), { settings: !elsewhere() })}\n`);
   if (!noOpen) {
     try {
       openerDir = mkdtempSync(join(tmpdir(), 'honestweek-view-'));
@@ -542,13 +479,25 @@ export async function runView({ argv = [], cwd = process.cwd(), env = process.en
   // A printed address can sit in terminal scrollback, so its code lasts printedTtlMs, not until used.
   const printed = (page) => handle.address('printed', page, { ttlMs: printedTtlMs });
   io.out(`Open this address in your browser: ${printed(homePage())}\n`);
+  // --page waits for Setup, which goes to Problems once saved, so say how to reach the page after it.
+  if (startAt?.page && setupFlow?.pending()) io.out(`Setup comes first. Once it's saved, type link ${startAt.page} here for an address to that page.\n`);
   if (selfTest) io.out(`The click-through test: ${printed(SELF_TEST_PAGE)}\n`);
   io.out(`Each address works once, within ${lifetime(printedTtlMs)}. Press Enter here to print a fresh one.\n`);
 
   let rl = null;
   if (input && typeof input.on === 'function') {
     rl = createInterface({ input, terminal: false });
-    rl.on('line', () => {
+    rl.on('line', (line) => {
+      // "link <page>": a fresh one-time address to that page (issue 198). Anything else, Enter
+      // included, prints a fresh address as before.
+      const asked = /^\s*link\s+(\S.*)$/.exec(String(line ?? ''));
+      if (asked) {
+        const target = pageLink(asked[1]);
+        if (target.error) io.out(`No link: ${target.error}\n`);
+        else if (setupFlow?.pending()) io.out('No link yet: finish Setup first, then ask again.\n');
+        else io.out(`Link: ${printed(target.page)}\n`);
+        return;
+      }
       io.out(`Fresh address: ${printed(homePage())}\n`);
       if (selfTest) io.out(`Fresh click-through test: ${printed(SELF_TEST_PAGE)}\n`);
     });

package/lib/worktrees.mjs

@@ -157,6 +157,35 @@ function sameFolder(a, b) {
   }
 }
 
+/**
+ * The folders of a repository's linked worktrees, as git recorded them: each
+ * `<commonDir>/worktrees/<name>/gitdir` holds the path of that worktree's own `.git`
+ * FILE, and the worktree is its parent folder. A worktree whose folder is gone keeps
+ * its recorded path until git prunes it. Empty when there are none or they can't be
+ * read. With `withLocks`, each is { path, locked }, locked when `git worktree lock` kept
+ * it from pruning. Reads files; never runs git.
+ */
+export function linkedWorkTrees(commonDir, { withLocks = false } = {}) {
+  const worktreesDir = join(commonDir, 'worktrees');
+  if (!existsSync(worktreesDir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(worktreesDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const pointer = readPointer(join(worktreesDir, e.name, 'gitdir'));
+    if (!pointer) continue;
+    const gitFile = isAbsolute(pointer) ? pointer : resolve(worktreesDir, e.name, pointer);
+    const path = dirname(gitFile);
+    out.push(withLocks ? { path, locked: existsSync(join(worktreesDir, e.name, 'locked')) } : path);
+  }
+  return out;
+}
+
 /**
  * resolveWorkTrees(root) -> string[]
  *
@@ -211,24 +240,8 @@ export function resolveWorkTrees(root) {
     // repository's common dir is the repo itself (not named ".git"), and has none.
     if (basename(normalize(commonDir)) === '.git') addEvery(dirname(commonDir));
 
-    const worktreesDir = join(commonDir, 'worktrees');
-    if (!existsSync(worktreesDir)) return out;
-    let entries;
-    try {
-      entries = readdirSync(worktreesDir, { withFileTypes: true });
-    } catch {
-      return out;
-    }
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      // `worktrees/<name>/gitdir` holds the absolute path of that worktree's own
-      // `.git` FILE; the worktree root is its parent directory. A pruned/stale entry
-      // simply yields a path that matches no session cwd — harmless.
-      const pointer = readPointer(join(worktreesDir, e.name, 'gitdir'));
-      if (!pointer) continue;
-      const gitFile = isAbsolute(pointer) ? pointer : resolve(worktreesDir, e.name, pointer);
-      addEvery(dirname(gitFile));
-    }
+    // A pruned/stale entry simply yields a path that matches no session cwd — harmless.
+    for (const p of linkedWorkTrees(commonDir)) addEvery(p);
   } catch {
     // Unreadable or malformed git metadata: attribution degrades to the given path.
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honestweek",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Find, replay and check your Claude Code and Codex sessions on your own machine, and turn a week of them into an honest, git-checked summary.",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "bin/",
     "lib/",
     "SKILL.md",
+    "flows/",
     "honestweek.config.example.json",
     ".claude-plugin/"
   ],