@marcomigozzi/trailhead 0.16.0 → 0.17.0

package/plugins/trailhead/hooks/lib/model-route.test.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Test per model-route.js (#323). Run: node model-route.test.js
+// Niente framework: assert semplici, stesso stile degli altri test di hooks/lib.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const LIB = path.join(__dirname, 'model-route.js');
+const root = path.resolve(__dirname, '..', '..', '..', '..');
+const { route, AGENT_OF, BALANCED, familyAlias, loadTierIds } = require(LIB);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const throws = (fn) => { try { fn(); } catch (e) { return true; } return false; };
+const TIERS = loadTierIds('claude');
+const OPUS = 'claude-opus-5-5';
+const SONNET = 'claude-sonnet-5-5';
+
+const claude = (extra) => route({ key: 'grill', host: 'claude', models: {}, sessionModel: SONNET, subagents: true, tierIds: TIERS, ...extra });
+const codex = (extra) => route({ key: 'grill', host: 'codex', models: {}, sessionModel: 'gpt-5.6-terra', subagents: true, tierIds: TIERS, ...extra });
+
+// --- Claude --------------------------------------------------------------------
+{
+  const r = claude({});
+  ok('claude: sonnet session, key unset -> dispatch trailhead-grill on opus',
+    r.route === 'dispatch' && r.agent === 'trailhead-grill' && r.model === OPUS && r.alias === 'opus');
+  ok('claude: strong comes from the current model-defaults entry', TIERS.strong === OPUS);
+  ok('claude: opus session, key unset -> inline', claude({ sessionModel: OPUS }).route === 'inline');
+  ok('claude: sonnet pin in a sonnet session -> inline', claude({ models: { grill: SONNET } }).route === 'inline');
+  ok('claude: inherit session -> inline', claude({ models: { grill: 'inherit session' } }).route === 'inline');
+  for (const unset of [null, '', undefined]) {
+    ok(`claude: ${JSON.stringify(unset)} resolves like an unset key`, claude({ models: { grill: unset } }).route === 'dispatch');
+  }
+  const pinned = claude({ sessionModel: OPUS, models: { grill: 'claude-opus-5' } });
+  ok('claude: a different opus version dispatches with the opus alias', pinned.route === 'dispatch' && pinned.alias === 'opus' && pinned.model === 'claude-opus-5');
+  ok('claude: a suffixed opus session + unset key -> inline', claude({ sessionModel: 'claude-opus-5-5[1m]' }).route === 'inline');
+  const sfx = claude({ sessionModel: 'claude-sonnet-5-5[1m]' });
+  ok('claude: a suffixed sonnet session + unset key -> dispatch opus', sfx.route === 'dispatch' && sfx.model === OPUS && sfx.alias === 'opus');
+  ok('claude: a suffixed configured id equals the plain session id', claude({ sessionModel: SONNET, models: { grill: `${SONNET}[1m]` } }).route === 'inline');
+  ok('claude: no subagents, suffixed session already on the model -> no suggestion', !claude({ subagents: false, sessionModel: 'claude-opus-5-5[1m]' }).suggest);
+  const unk = claude({ models: { grill: 'my-custom-model' } });
+  ok('claude: an unknown id that differs from the session -> inline with warning', unk.route === 'inline' && unk.warning === 'unknown-id');
+  const unkEq = claude({ sessionModel: 'my-custom-model', models: { grill: 'my-custom-model' } });
+  ok('claude: an unknown id equal to the session -> inline, no warning', unkEq.route === 'inline' && !unkEq.warning);
+  const unknownSession = claude({ sessionModel: 'unknown' });
+  ok('claude: session unknown, key unset -> dispatch', unknownSession.route === 'dispatch');
+  ok('claude: a pin literally named unknown never equals the reserved value',
+    claude({ sessionModel: 'unknown', models: { grill: 'unknown' } }).route === 'inline' && claude({ sessionModel: 'unknown', models: { grill: 'unknown' } }).warning === 'unknown-id');
+  const ns = claude({ subagents: false });
+  ok('claude: no subagents -> inline with a suggestion of the resolved id', ns.route === 'inline' && ns.suggest === OPUS);
+  ok('claude: no subagents and already on that model -> no suggestion', !claude({ subagents: false, sessionModel: OPUS }).suggest);
+  ok('claude: no subagents and unknown session -> suggestion', claude({ subagents: false, sessionModel: 'unknown' }).suggest === OPUS);
+  ok('claude: alias families', familyAlias('claude-opus-5-5') === 'opus' && familyAlias('claude-sonnet-5') === 'sonnet' &&
+    familyAlias('claude-haiku-4-5-20251001') === 'haiku' && familyAlias('claude-fable-5') === 'fable' && familyAlias('gpt-5.6-sol') === null);
+  ok('claude: the config key for another activity uses its own Balanced tier',
+    route({ key: 'codebase-map', host: 'claude', models: {}, sessionModel: OPUS, subagents: true, tierIds: TIERS }).model === TIERS.fast);
+  ok('claude: models.codex.grill is ignored on the claude host',
+    claude({ models: { codex: { grill: 'gpt-5.6-sol' } } }).model === OPUS);
+}
+
+// --- #323: grill non impostato segue plan ---
+{
+  const g = claude({ sessionModel: OPUS, models: { plan: SONNET } });
+  ok('grill unset follows plan: plan sonnet in an opus session -> dispatch sonnet',
+    g.route === 'dispatch' && g.agent === 'trailhead-grill' && g.model === SONNET && g.alias === 'sonnet');
+  const bal = claude({ sessionModel: SONNET, models: {} });
+  ok('grill unset + plan unset in a sonnet session -> dispatch opus (plan Balanced default)', bal.route === 'dispatch' && bal.model === OPUS && bal.alias === 'opus');
+  ok('grill unset + plan equal to the session -> inline', claude({ sessionModel: SONNET, models: { plan: SONNET } }).route === 'inline');
+  const own = claude({ sessionModel: OPUS, models: { plan: SONNET, grill: 'claude-haiku-5-5' } });
+  ok('grill set overrides plan', own.route === 'dispatch' && own.model === 'claude-haiku-5-5');
+  ok('plan inherit session + grill unset -> inline', claude({ models: { plan: 'inherit session' } }).route === 'inline');
+  ok('grill inherit session wins over plan', claude({ models: { plan: OPUS, grill: 'inherit session' } }).route === 'inline');
+  for (const unset of [null, '']) {
+    ok(`grill ${JSON.stringify(unset)} follows plan`, claude({ sessionModel: OPUS, models: { plan: SONNET, grill: unset } }).model === SONNET);
+  }
+  const old = { plan: SONNET, execute: SONNET, research: SONNET, review: SONNET, debug: SONNET, verify: SONNET, 'codebase-map': 'claude-haiku-5-5' };
+  const legacy = claude({ sessionModel: OPUS, models: old });
+  ok('a config with the seven old keys and no grill grills on the plan id', legacy.route === 'dispatch' && legacy.model === SONNET);
+  ok('other keys do not follow plan', route({ key: 'research', host: 'claude', models: { plan: SONNET }, sessionModel: SONNET, subagents: true, tierIds: TIERS }).route === 'inline');
+  const noSub = claude({ sessionModel: OPUS, subagents: false, models: { plan: SONNET } });
+  ok('no subagents: suggests the plan id', noSub.route === 'inline' && noSub.suggest === SONNET);
+}
+
+// --- Codex ---------------------------------------------------------------------
+{
+  ok('codex: key unset -> inline', codex({}).route === 'inline');
+  ok('codex: inherit session -> inline', codex({ models: { codex: { grill: 'inherit session' } } }).route === 'inline');
+  ok('codex: models.grill (claude ids) is ignored', codex({ models: { grill: OPUS } }).route === 'inline');
+  const d = codex({ models: { codex: { grill: 'gpt-5.6-sol' } } });
+  ok('codex: a pin different from the session -> dispatch trailhead-grill', d.route === 'dispatch' && d.agent === 'trailhead-grill' && d.alias === null && d.model === 'gpt-5.6-sol');
+  ok('codex: a bare pin equal to the session -> inline', codex({ sessionModel: 'gpt-5.6-sol', models: { codex: { grill: 'gpt-5.6-sol' } } }).route === 'inline');
+  const pin = { model: 'gpt-5.6-sol', effort: 'high' };
+  const eq = { sessionModel: 'gpt-5.6-sol', models: { codex: { grill: pin } } };
+  ok('codex: equal model and equal effort -> inline', codex({ ...eq, sessionEffort: 'high' }).route === 'inline');
+  ok('codex: equal model, different effort -> dispatch', codex({ ...eq, sessionEffort: 'medium' }).route === 'dispatch');
+  ok('codex: equal model, effort pinned, session effort unknown -> dispatch', codex(eq).route === 'dispatch');
+  ok('codex: equal model, no pinned effort, any session effort -> inline',
+    codex({ sessionModel: 'gpt-5.6-sol', sessionEffort: 'low', models: { codex: { grill: { model: 'gpt-5.6-sol' } } } }).route === 'inline');
+  ok('codex: session unknown -> dispatch', codex({ sessionModel: 'unknown', models: { codex: { grill: 'gpt-5.6-sol' } } }).route === 'dispatch');
+  ok('codex: an object pin without a model stays inline', codex({ models: { codex: { grill: { effort: 'high' } } } }).route === 'inline');
+  ok('codex: execute dispatches the projected trailhead-execute',
+    route({ key: 'execute', host: 'codex', models: { codex: { execute: 'gpt-5.6-sol' } }, sessionModel: 'gpt-5.6-terra', subagents: true, tierIds: TIERS }).agent === 'trailhead-execute');
+}
+
+{
+  const cx = (extra) => codex({ ...extra });
+  const planPin = { codex: { plan: 'gpt-5.6-sol' } };
+  const d = cx({ models: planPin });
+  ok('codex: grill unset + codex.plan pinned -> dispatch trailhead-grill on the plan pin', d.route === 'dispatch' && d.agent === 'trailhead-grill' && d.model === 'gpt-5.6-sol');
+  ok('codex: grill unset + codex.plan equal to the session -> inline', cx({ sessionModel: 'gpt-5.6-sol', models: planPin }).route === 'inline');
+  ok('codex: plan pin with effort follows the same effort rules',
+    cx({ sessionModel: 'gpt-5.6-sol', models: { codex: { plan: { model: 'gpt-5.6-sol', effort: 'high' } } } }).route === 'dispatch' &&
+    cx({ sessionModel: 'gpt-5.6-sol', sessionEffort: 'high', models: { codex: { plan: { model: 'gpt-5.6-sol', effort: 'high' } } } }).route === 'inline');
+  ok('codex: grill set overrides plan', cx({ sessionModel: 'gpt-5.6-sol', models: { codex: { plan: 'gpt-5.6-terra', grill: 'gpt-5.6-sol' } } }).route === 'inline');
+  ok('codex: grill inherit session wins over plan', cx({ models: { codex: { plan: 'gpt-5.6-sol', grill: 'inherit session' } } }).route === 'inline');
+  for (const [label, pinv] of [['object form', { model: 'inherit session', effort: 'high' }], ['case variant', ' Inherit Session '], ['bare string', 'inherit session']]) {
+    ok(`codex: plan ${label} of inherit session + grill unset -> inline`, cx({ models: { codex: { plan: pinv } } }).route === 'inline');
+    ok(`codex: grill ${label} of inherit session wins over a plan pin -> inline`, cx({ models: { codex: { plan: 'gpt-5.6-sol', grill: pinv } } }).route === 'inline');
+  }
+  ok('claude: a case variant of inherit session routes inline', claude({ models: { grill: ' Inherit Session ' } }).route === 'inline' && claude({ models: { plan: 'INHERIT SESSION' } }).route === 'inline');
+  ok('codex: grill unset + plan unset -> inline', cx({ models: { codex: {} } }).route === 'inline');
+}
+
+// --- agent mapping -------------------------------------------------------------
+{
+  const { MODEL_KEYS, codexAgentTomlPlan } = require(path.join(root, 'bin', 'lib', 'codex-projection.js'));
+  const keys = [...MODEL_KEYS].sort();
+  ok('agents: both tables cover exactly the MODEL_KEYS',
+    JSON.stringify(Object.keys(AGENT_OF.claude).sort()) === JSON.stringify(keys) &&
+    JSON.stringify(Object.keys(AGENT_OF.codex).sort()) === JSON.stringify(keys));
+  for (const [key, name] of Object.entries(AGENT_OF.claude)) {
+    ok(`agents: claude ${key} -> ${name} exists under agents/`, fs.existsSync(path.join(root, 'plugins', 'trailhead', 'agents', `${name}.md`)));
+  }
+  const defs = fs.readdirSync(path.join(root, 'plugins', 'trailhead', 'agents'))
+    .filter((f) => /^trailhead-.*\.md$/.test(f)).sort()
+    .map((f) => ({ name: f.slice(0, -3), description: 'd', tools: 'Read', body: 'b' }));
+  const models = Object.fromEntries(keys.map((k) => [k, `pin-${k}`]));
+  const writes = codexAgentTomlPlan('/c', models, defs).writes;
+  for (const [key, name] of Object.entries(AGENT_OF.codex)) {
+    const w = writes.find((x) => x.content.includes(`model = "pin-${key}"`));
+    ok(`agents: codex ${key} -> ${name} is the name the projection emits`, !!w && w.name === name);
+  }
+  ok('agents: execute and review map to the distinct per-host names',
+    AGENT_OF.claude.execute === 'trailhead-executor' && AGENT_OF.codex.execute === 'trailhead-execute' &&
+    AGENT_OF.claude.review === 'trailhead-code-review' && AGENT_OF.codex.review === 'trailhead-review');
+  ok('agents: an unknown key throws', throws(() => route({ key: 'nope', host: 'claude', models: {}, sessionModel: 'unknown', subagents: true, tierIds: TIERS })));
+  ok('agents: an unknown host throws', throws(() => route({ key: 'grill', host: 'mars', models: {}, sessionModel: 'unknown', subagents: true, tierIds: TIERS })));
+}
+
+// --- BALANCED pinned to the profile table -----------------------------------------
+{
+  const ref = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', '_shared', 'configuration-reference.md'), 'utf8').split('\n');
+  const cells = (l) => l.split('|').slice(1, -1).map((c) => c.trim());
+  const header = cells(ref.find((l) => l.startsWith('| profile |')));
+  const row = cells(ref.find((l) => l.startsWith('| **Balanced** |')));
+  const parsed = Object.fromEntries(header.slice(1).map((k, i) => [k, row[i + 1]]));
+  const { grill: tableGrill, ...tableRest } = parsed;
+  ok('BALANCED equals the Balanced row of the profile table, minus grill', JSON.stringify(BALANCED) === JSON.stringify(tableRest) && !('grill' in BALANCED));
+  ok('the grill column mirrors the plan column in every profile', ['High', 'Balanced', 'Low'].every((name) => {
+    const r = cells(ref.find((l) => l.startsWith(`| **${name}** |`)));
+    return r[header.indexOf('grill')] === r[header.indexOf('plan')];
+  }) && tableGrill === parsed.plan);
+}
+
+// --- CLI -----------------------------------------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-model-route-'));
+  const globalDir = path.join(tmp, 'claude');
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-sonnet-5', plan: 'claude-haiku-5-5' } }));
+  const proj = path.join(tmp, 'proj');
+  fs.mkdirSync(path.join(proj, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-opus-5' } }));
+  const env = { ...process.env, CLAUDE_CONFIG_DIR: globalDir, CODEX_HOME: path.join(tmp, 'codex') };
+  const run = (args) => spawnSync(process.execPath, [LIB, ...args], { encoding: 'utf8', env });
+  const r = run(['grill', '--session', SONNET, proj]);
+  const j = JSON.parse(r.stdout);
+  ok('cli: exit 0 and one JSON line with the six keys',
+    r.status === 0 && r.stdout.trim().split('\n').length === 1 &&
+    JSON.stringify(Object.keys(j)) === JSON.stringify(['route', 'agent', 'model', 'alias', 'suggest', 'warning']));
+  ok('cli: the project config wins over the global one key by key', j.route === 'dispatch' && j.model === 'claude-opus-5' && j.alias === 'opus' && j.agent === 'trailhead-grill');
+  const g = JSON.parse(run(['grill', '--session', SONNET, tmp]).stdout);
+  ok('cli: with no project above, the global config applies', g.route === 'dispatch' && g.model === 'claude-sonnet-5' && g.alias === 'sonnet');
+  const ns = JSON.parse(run(['grill', '--session', 'unknown', '--no-subagents', proj]).stdout);
+  ok('cli: --no-subagents inline with a suggestion', ns.route === 'inline' && ns.suggest === 'claude-opus-5');
+  const cx = JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout);
+  ok('cli: --host codex ignores models.grill', cx.route === 'inline');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { codex: { grill: { model: 'gpt-5.6-sol', effort: 'high' } } } }));
+  const ce = JSON.parse(run(['grill', '--session', 'gpt-5.6-sol', '--session-effort', 'high', '--host', 'codex', proj]).stdout);
+  ok('cli: --session-effort equal to the pinned effort -> inline', ce.route === 'inline');
+  const cd = JSON.parse(run(['grill', '--session', 'gpt-5.6-sol', '--session-effort', 'medium', '--host', 'codex', proj]).stdout);
+  ok('cli: a different --session-effort -> dispatch', cd.route === 'dispatch' && cd.agent === 'trailhead-grill');
+  for (const [name, args] of [
+    ['a missing --session', ['grill', proj]],
+    ['an empty --session', ['grill', '--session', '', proj]],
+    ['an unknown flag', ['grill', '--session', SONNET, '--bogus', proj]],
+    ['an unknown key', ['nope', '--session', SONNET, proj]],
+    ['no key', ['--session', SONNET]],
+    ['an unknown host', ['grill', '--session', SONNET, '--host', 'mars', proj]],
+  ]) {
+    const x = run(args);
+    ok(`cli: ${name} exits 2 with nothing on stdout`, x.status === 2 && x.stdout === '' && x.stderr.length > 0);
+  }
+  // implicit grill per layer (project plan beats a global grill)
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-haiku-5-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5' } }));
+  const lp = JSON.parse(run(['grill', '--session', OPUS, proj]).stdout);
+  ok('cli: project plan + no project grill beats a global grill', lp.route === 'dispatch' && lp.model === 'claude-sonnet-5');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5', grill: 'claude-opus-5' } }));
+  ok('cli: a project grill always wins', JSON.parse(run(['grill', '--session', SONNET, proj]).stdout).model === 'claude-opus-5');
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: {} }));
+  ok('cli: global plan + no grill anywhere -> global plan', JSON.parse(run(['grill', '--session', OPUS, proj]).stdout).model === 'claude-sonnet-5');
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-haiku-5-5', plan: 'claude-opus-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'inherit session' } }));
+  ok('cli: project plan inherit session + global grill -> inline', JSON.parse(run(['grill', '--session', SONNET, proj]).stdout).route === 'inline');
+  // codex
+  const codexHome = path.join(tmp, 'codex');
+  fs.mkdirSync(path.join(codexHome, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(codexHome, 'trailhead', 'config.json'), JSON.stringify({ models: { codex: { grill: 'gpt-5.6-luna' } } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { codex: { plan: 'gpt-5.6-sol' } } }));
+  const cxl = JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout);
+  ok('cli codex: project codex.plan + no project grill beats a global codex.grill', cxl.route === 'dispatch' && cxl.model === 'gpt-5.6-sol');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: {} }));
+  ok('cli codex: only a global grill pin -> that pin', JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout).model === 'gpt-5.6-luna');
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`model-route.test.js: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/report-status.test.js

@@ -16,13 +16,15 @@ const fs = require('fs');
 const os = require('os');
 
 const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-report-status.js');
-const { checkReport, TOKENS, CONTRACTS, FAMILY_OF } = require(scriptPath);
+const { checkReport, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES } = require(scriptPath);
 const techDir = path.resolve(__dirname, '..', '..', 'skills', '_shared', 'techniques');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 
 const K = 'critical: 0 · warning: 1 · info: 2'; // the counts line
+const K1 = 'critical: 1 · warning: 0 · info: 0';
+const K2 = 'critical: 2 · warning: 1 · info: 0';
 const V = 'verify';
 const C = 'code-review';
 const KEYS = ['action', 'verdict', 'problem', 'report', 'fields', 'body'];
@@ -119,6 +121,60 @@ const rows = [
   ['two counts lines', C, `status: clean\n${K}\nbody\n${K}\n`, ['reask', null, 'counts']],
   ['two different counts lines', C, `status: clean\n${K}\ncritical: 1 · warning: 1 · info: 2\n`, ['reask', null, 'counts']],
   ['counts only inside a code fence', C, `status: clean\n\`\`\`\n${K}\n\`\`\`\n`, ['reask', null, 'counts']],
+
+  // --- verdict vs content: code-review fails closed on an unclosed Critical ---
+  ['clean with critical 2 and no ledger (ticket repro)', C, `status: clean\n${K2}\n\n- critical: SQL injection\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\n\n- critical: SQL injection\n`]],
+  ['clean, critical 1, C1 fixed', C, `status: clean\n${K1}\nC1 fixed (abc123)\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 deferred', C, `status: clean\n${K1}\n- C1: deferred → #12\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 accepted', C, `status: clean\n${K1}\nC1 accepted: false positive\n`, ['accept', 'clean', null]],
+  ['clean, critical 2, only C1 closed', C, `status: clean\n${K2}\nC1 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\n`]],
+  ['clean, critical 1, C1 open', C, `status: clean\n${K1}\nC1 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 open\n`]],
+  ['clean, critical 1, C1 fixed and C2 open', C, `status: clean\n${K1}\nC1 fixed (a)\nC2 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed (a)\nC2 open\n`]],
+  ['clean, critical 1, only a reclassified pointer', C, `status: clean\n${K1}\nC1 reclassified as W3\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 reclassified as W3\n`]],
+  ['clean, critical 1, ledger line only inside a fence', C, `status: clean\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`]],
+  ['clean, critical 2, a repeated C1 line counts once', C, `status: clean\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`]],
+  ['finding prose with open after a closed ledger line stays clean', C, `status: clean\n${K1}\nC1: fixed (abc)\nC1 file.js:3 handler leaves the socket open\n`, ['accept', 'clean', null]],
+  ['open redirect prose with a fixed ledger stays clean', C, `status: clean\n${K1}\nC1 fixed (abc)\nC1 open redirect in login.js:9\n`, ['accept', 'clean', null]],
+  ['a lone fixed-size prose line does not close the Critical', C, `status: clean\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`]],
+  ['bold id and en-dash separator ledger line', C, `status: clean\n${K1}\n- **C1** – fixed (abc)\n`, ['accept', 'clean', null]],
+  ['verify subclass is not a class line', V, 'status: met\n- a, subclass: unmet\n', ['accept', 'met', null]],
+  ['an unparsed open line for an uncounted Critical fails closed', C, `status: clean\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`]],
+  ['em dash separator closes the Critical', C, `status: clean\n${K1}\nC1 ${String.fromCharCode(0x2014)} fixed (abc)\n`, ['accept', 'clean', null]],
+  ['still open fails closed', C, `status: clean\n${K1}\nC1: still open\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1: still open\nC2 fixed (a)\n`]],
+  ['bracketed open fails closed', C, `status: clean\n${K1}\nC1 [open]\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 [open]\nC2 fixed (a)\n`]],
+  ['a reclassified Critical does not gate the rest', C, `status: clean\n${K1}\nC1 reclassified as W3\nC2 fixed (a)\n`, ['accept', 'clean', null]],
+  ['clean, critical 0, warnings open never gate', C, `status: clean\n${K}\nW1 open\n`, ['accept', 'clean', null]],
+  ['issues_found is never changed', C, `status: issues_found\n${K1}\nC1 fixed (a)\n`, ['accept', 'issues_found', null]],
+
+  // --- verdict vs content: verify raises the tag to the highest claim class ---
+  ['verify met with a met claim', V, 'status: met\n- claim 1, class: met\n', ['accept', 'met', null]],
+  ['verify met with an unmet claim', V, 'status: met\n- Claim 2: login wired, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- Claim 2: login wired, class: unmet\n']],
+  ['verify met with a partial claim', V, 'status: met\n- claim 1, class: partial\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- claim 1, class: partial\n']],
+  ['verify met with an inconclusive claim', V, 'status: met\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n',
+    ['normalise', 'inconclusive', null, 'status: inconclusive\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n']],
+  ['verify met with inconclusive and unmet', V, 'status: met\n- a, class: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, class: inconclusive\n- b, class: unmet\n']],
+  ['verify inconclusive with an unmet claim', V, 'status: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- b, class: unmet\n']],
+  ['verify gaps_found with only met claims stays', V, 'status: gaps_found\n- a, class: met\n', ['accept', 'gaps_found', null]],
+  ['verify inconclusive with only met claims stays', V, 'status: inconclusive\n- a, class: met\n', ['accept', 'inconclusive', null]],
+  ['verify class line inside a fence is ignored', V, 'status: met\n```\n- a, class: unmet\n```\n', ['accept', 'met', null]],
+  ['verify class line inside a blockquote is ignored', V, 'status: met\n> - a, class: unmet\n', ['accept', 'met', null]],
+  ['verify upper-case class counts', V, 'status: met\n- a, Class: UNMET\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, Class: UNMET\n']],
 ];
 
 for (const [name, technique, input, expected] of rows) {
@@ -161,6 +217,9 @@ const frows = [
   ['codebase-map needs_input with questions', 'codebase-map', 'status: needs_input\nanswer: partial\nevidence: a.js:1\nopen questions: which root?\n', ['accept', 'needs_input', null, null, null]],
   ['plan ready, body is the rest', 'plan', 'status: ready\n\n## Steps\n1. a\n2. b\n\nVerification: x\n', ['accept', 'ready', null, {}, '## Steps\n1. a\n2. b\n\nVerification: x']],
   ['plan needs_input', 'plan', 'status: needs_input\nquestions:\n1. Which db?\n2. Keep v1?\n', ['accept', 'needs_input', null, { questions: '1. Which db?\n2. Keep v1?' }, null]],
+  ['grilling question round', 'grill', 'status: question\nsettled: none\nfrontier: Q1, Q2\nquestion: 1. Which db?\nrecommended: A\nWeak point: it costs more.\namendments: none\nconflicts: none\n', ['accept', 'question', null,
+    { settled: 'none', frontier: 'Q1, Q2', question: '1. Which db?', recommended: 'A\nWeak point: it costs more.', amendments: 'none', conflicts: 'none' }, null]],
+  ['grilling review round', 'grill', 'status: review\nsettled: Q1 A, because x\nfrontier: none\namendments: Q1: tighten the wording\nconflicts: Q1 vs Q2: reconcile them. Weak point: none\n', ['accept', 'review', null, null, null]],
   // --- normalise: layout, fields intact ---
   ['bold label and token, bullets', EX, '**Status:** DONE\n- **commits:** abc1234 feat: x\n- tests: ok\n- deviations: none\n- blockers: none\n', ['normalise', 'done', null,
     { commits: 'abc1234 feat: x', tests: 'ok', deviations: 'none', blockers: 'none' }, null,
@@ -197,6 +256,14 @@ const frows = [
     'A feature about statuses:\n```\nstatus: pending\n```\nDone.']],
   ['a blockquoted status line inside an answer is ignored', 'research', 'status: found\nanswer: see\n> status: pending\nevidence: e\nopen questions: none\n', ['accept', 'found', null, null, null]],
   ['prose after the last field becomes its value, so a done report reasks', EX, fullImpl('done', 'none', 'Note: hi\n'), ['reask', null, 'fields']],
+  ['grilling question without recommended', 'grill', 'status: question\nsettled: none\nfrontier: Q1\nquestion: 1. Which db?\namendments: none\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling question with an empty question', 'grill', 'status: question\nsettled: none\nfrontier: Q1\nquestion: none\nrecommended: A\namendments: none\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling question with conflicts', 'grill', 'status: question\nsettled: none\nfrontier: Q1\nquestion: 1. Which db?\nrecommended: A\namendments: none\nconflicts: Q1 vs Q2\n', ['reask', null, 'fields']],
+  ['grilling question with amendments', 'grill', 'status: question\nsettled: none\nfrontier: Q1\nquestion: 1. Which db?\nrecommended: A\namendments: Q1: x\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling review with a frontier', 'grill', 'status: review\nsettled: Q1 A\nfrontier: Q2\namendments: none\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling review with a question', 'grill', 'status: review\nsettled: Q1 A\nfrontier: none\nquestion: 2. More?\namendments: none\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling review without amendments', 'grill', 'status: review\nsettled: Q1 A\nfrontier: none\nconflicts: none\n', ['reask', null, 'fields']],
+  ['grilling: ready is an unknown token', 'grill', 'status: ready\nsettled: none\nfrontier: none\namendments: none\nconflicts: none\n', ['reask', null, 'unknown-token']],
   ['the same label twice', EX, fullImpl('done', 'none', 'tests: again\n'), ['reask', null, 'fields']],
 ];
 for (const [name, technique, input, expected] of frows) {
@@ -233,6 +300,13 @@ for (const [name, technique, input, expected] of frows) {
   ok('a report with an unterminated fence still parses its leading fields', checkReport('status: found\nanswer: a\nevidence: e\nopen questions: none\n```\nx', 'research').action === 'accept');
 }
 
+{
+  const r = checkReport('status: review\nsettled: Q1 A\nfrontier: none\namendments: none\nconflicts: none\n', 'grill');
+  ok('grill: Weak point is not a field label and body is null', r.body === null && !('weak point' in r.fields));
+  const q = checkReport('status: question\nsettled: none\nfrontier: Q1\nquestion: 1. Which?\nrecommended: A\nWeak point: x\nWeak point: y\namendments: none\nconflicts: none\n', 'grill');
+  ok('grill: two Weak point lines do not trigger a reask', q.action === 'accept' && q.body === null);
+}
+
 // --- misuse ---------------------------------------------------------------------
 ok('checkReport: unknown technique throws', (() => { try { checkReport('status: met', 'bogus'); } catch (e) { return true; } return false; })());
 ok('checkReport: missing technique throws', (() => { try { checkReport('status: met'); } catch (e) { return true; } return false; })());
@@ -261,7 +335,7 @@ ok('vocabulary: code-review tokens equal the ones code-review.md defines',
     const [lhs, rhs] = l.split('=>');
     return { when: [...lhs.matchAll(/`([^`]+)`/g)].map((m) => m[1]), field: /`([^`]+)`/.exec(rhs)[1], rule: /(non-empty|none)\.$/.exec(rhs)[1] };
   });
-  for (const family of ['implementing', 'investigating', 'plan']) {
+  for (const family of ['implementing', 'investigating', 'plan', 'grilling']) {
     const block = blocks[family];
     ok(`contracts: source defines the ${family} block`, typeof block === 'string');
     ok(`contracts: ${family} tokens equal the source`, JSON.stringify(CONTRACTS[family].tokens) === JSON.stringify(words(block, 'statuses')));
@@ -274,6 +348,17 @@ ok('vocabulary: code-review tokens equal the ones code-review.md defines',
     ok(`contracts: technique ${technique} maps to the family of trailhead-${technique} in the sync script`, FAMILIES[`trailhead-${technique}`] === family);
     ok(`contracts: TOKENS.${technique} are the ${family} tokens`, JSON.stringify(TOKENS[technique]) === JSON.stringify(CONTRACTS[family].tokens));
   }
+  // the reviewing block names the verify class vocabulary and the closing dispositions
+  const bullet = (block, prefix) => block.split('\n').find((l) => l.startsWith(`- ${prefix}:`)) || '';
+  const classTokens = (text) => [...text.matchAll(/class: <([a-z|]+)>/g)].flatMap((m) => m[1].split('|'));
+  ok('contracts: reviewing verify bullet names the checker class vocabulary',
+    JSON.stringify(classTokens(bullet(blocks.reviewing, 'trailhead-verify'))) === JSON.stringify(VERIFY_CLASSES));
+  const crBullet = bullet(blocks.reviewing, 'trailhead-code-review');
+  ok('contracts: reviewing code-review bullet names the closing dispositions',
+    ['fixed', 'deferred', 'accepted'].every((d) => new RegExp(`\\x60${d}\\x60`).test(crBullet)));
+  const verifyDoc = fs.readFileSync(path.join(techDir, 'verify.md'), 'utf8');
+  ok('contracts: verify.md names the same class vocabulary',
+    classTokens(verifyDoc.replace(/class: ([a-z]+(?: \| [a-z]+)+)/g, (m, g) => `class: <${g.replace(/ \| /g, '|')}>`)).join() === VERIFY_CLASSES.join());
   ok('contracts: every non-review agent has a technique here',
     Object.entries(FAMILIES).filter(([, f]) => f !== 'reviewing').every(([a]) => FAMILY_OF[a.replace(/^trailhead-/, '')] !== undefined));
 }
@@ -344,7 +429,44 @@ const oneLine = (out) => { const lines = out.split('\n').filter(Boolean); return
   const jf = oneLine(f.out);
   ok('cli --file: a report over 64 KB arrives whole through a pipe', f.code === 0 && !!jf && jf.report === big);
 }
+// --- --task-output: the report read from a background agent's transcript ----------
+// The host's task .output is JSONL; one assistant message can span several lines
+// (same message.id), and tool_use, user and bookkeeping lines sit between them.
+const line = (o) => JSON.stringify(o);
+const asst = (id, content) => line({ type: 'assistant', message: { id, role: 'assistant', content } });
+const transcript = [
+  line({ type: 'user', message: { role: 'user', content: 'brief' } }),
+  asst('m1', [{ type: 'text', text: 'status: gaps_found\nearly draft' }]),
+  asst('m1', [{ type: 'tool_use', id: 't1', name: 'Bash', input: {} }]),
+  line({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }] } }),
+  asst('m2', [{ type: 'text', text: 'status: met\n' }]),
+  asst('m2', [{ type: 'text', text: 'final body\n' }]),
+  line({ type: 'attachment', attachment: {} }),
+  'not json at all',
+  '',
+].join('\n');
+{
+  const { reportFromTaskOutput } = require(scriptPath);
+  ok('task output: the last assistant message, its text blocks joined in order',
+    reportFromTaskOutput(transcript) === 'status: met\nfinal body\n');
+  ok('task output: a trailing tool_use-only message is skipped for the last one with text',
+    reportFromTaskOutput(`${transcript}\n${asst('m3', [{ type: 'tool_use', id: 't2', name: 'Read', input: {} }])}`) === 'status: met\nfinal body\n');
+  ok('task output: string content counts as text', reportFromTaskOutput(asst('m9', 'status: met\nx')) === 'status: met\nx');
+  ok('task output: no assistant text is null', reportFromTaskOutput(line({ type: 'user', message: { content: 'hi' } })) === null);
+  const r = cli(['--technique', 'verify', '--task-output', file('agent.output', transcript)]);
+  const j = oneLine(r.out);
+  ok('cli --task-output: exit 0, the report checked as accept', r.code === 0 && !!j && j.action === 'accept' && j.verdict === 'met' && j.report === 'status: met\nfinal body\n');
+  const target = file('agent.jsonl', transcript);
+  const link = path.join(tmp, 'linked.output');
+  fs.symlinkSync(target, link);
+  const s = oneLine(cli(['--technique', 'verify', '--task-output', link]).out);
+  ok('cli --task-output: follows the host symlink to the transcript', !!s && s.verdict === 'met');
+}
 const usageErrors = [
+  ['--file and --task-output together', ['--technique', 'verify', '--file', file('g.md', 'status: met'), '--task-output', file('g.output', transcript)]],
+  ['--task-output without a value', ['--technique', 'verify', '--task-output']],
+  ['--task-output with no assistant text', ['--technique', 'verify', '--task-output', file('h.output', line({ type: 'user', message: { content: 'x' } }))]],
+  ['unreadable --task-output', ['--technique', 'verify', '--task-output', path.join(tmp, 'nope.output')]],
   ['no technique', ['--file', file('d.md', 'status: met')]],
   ['unknown technique', ['--technique', 'bogus', '--file', file('e.md', 'status: met')]],
   ['technique without a value', ['--technique']],

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -633,6 +633,23 @@ const SEARCH_VERB_CONFIG = {
   awk: { patternFirst: true, valueFlags: new Set(['-f', '-v']), patternFlags: new Set() },
 };
 
+// #316: the -f / --file operand of a flag token, or null when the token is not one.
+// Forms: `-f V`, `-fV`, a short cluster whose FIRST value-taking letter is `f`
+// (`-if.env`; after another value letter the rest is that flag's value, so
+// `-ef.env` is a pattern), `--file V`, `--file=V`. `consumed` = extra tokens used.
+function fileFlagOperand(t, next, config) {
+  if (t === '--file') return { value: next, consumed: 1 };
+  if (t.startsWith('--file=')) return { value: t.slice('--file='.length), consumed: 0 };
+  if (t.startsWith('--')) return null;
+  for (let i = 1; i < t.length; i++) {
+    if (!config.valueFlags.has(`-${t[i]}`)) continue;
+    if (t[i] !== 'f') return null;
+    const rest = t.slice(i + 1);
+    return rest ? { value: rest, consumed: 0 } : { value: next, consumed: 1 };
+  }
+  return null;
+}
+
 // Walk a verb's argument tokens (verb itself already stripped), skipping
 // flags (and their separate-token values), an explicit `--` end-of-options
 // marker (which must not itself swallow the next real positional), and the
@@ -647,6 +664,14 @@ function scanArgsSkippingPattern(args, config, isMatch) {
     const t = args[j];
     if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
     if (!afterDashDash && t.startsWith('-') && t !== '-') {
+      // #316: the value of -f / --file is a FILE the verb reads, so it is tested.
+      const file = fileFlagOperand(t, args[j + 1], config);
+      if (file) {
+        if (file.value !== undefined && file.value !== '' && isMatch(file.value)) return file.value;
+        patternConsumed = true; // the pattern/script comes from that file, so positionals are FILEs
+        j += file.consumed;
+        continue;
+      }
       if (config.valueFlags.has(t)) {
         j++; // consume its separate-token value
         if (config.patternFlags && config.patternFlags.has(t)) patternConsumed = true;

package/plugins/trailhead/hooks/lib/statusline-context.test.js

@@ -136,5 +136,26 @@ eq('edge threshold', pct(1000, edge), 100);
 // finestra minuscola: soglia mai sotto 1
 eq('tiny window guard', pct(5, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '10' } }), 100);
 
-fs.rmSync(root, { recursive: true, force: true });
+// --- credenziali: il blocco usage legge .credentials.json da CLAUDE_CONFIG_DIR (#320) ---
+// Segnale osservabile: la dir cache viene creata solo se il guard sulle credenziali passa.
+function usageReached({ withCreds }) {
+  const credCfg = path.join(root, withCreds ? 'cfg-creds' : 'cfg-nocreds');
+  const cache = path.join(root, withCreds ? 'cache-creds' : 'cache-nocreds');
+  fs.mkdirSync(credCfg, { recursive: true });
+  fs.mkdirSync(cache, { recursive: true });
+  if (withCreds) {
+    fs.writeFileSync(path.join(credCfg, '.credentials.json'), JSON.stringify({ claudeAiOauth: { accessToken: 'dummy' } }));
+  }
+  const env = { ...process.env, NO_COLOR: '1', HOME: home, CLAUDE_CONFIG_DIR: credCfg, XDG_CACHE_HOME: cache,
+    USAGE_API_TIMEOUT: '1', HTTPS_PROXY: 'http://127.0.0.1:9', https_proxy: 'http://127.0.0.1:9' };
+  delete env.TRAILHEAD_STATUSLINE_USAGE;
+  const input = { model: { id: 'claude-opus-5-5', display_name: 'Test' }, workspace: { project_dir: proj, current_dir: proj } };
+  spawnSync('bash', [script, '--context-only'], { input: JSON.stringify(input), env, encoding: 'utf8' });
+  return fs.existsSync(path.join(cache, 'trailhead-statusline'));
+}
+ok('usage block reached with creds under CLAUDE_CONFIG_DIR', usageReached({ withCreds: true }));
+ok('usage block skipped without creds', !usageReached({ withCreds: false }));
+
+// retry: il python in background puo' ancora scrivere nella cache mentre si pulisce
+fs.rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
 console.log(`statusline-context.test.js: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/unmodelled.js

@@ -62,6 +62,11 @@ const WRAPPER_VALUE_FLAGS = {
   nohup: [],
 };
 
+// Is `word` (as written, quotes allowed) a command wrapper from the list above? #316
+function isWrapperWord(word) {
+  return Object.prototype.hasOwnProperty.call(WRAPPER_VALUE_FLAGS, dequote(word));
+}
+
 // Index just past a wrapper's own flags (and assignments), from the wrapper at toks[k].
 function skipWrapper(toks, k) {
   const w = dequote(toks[k]);
@@ -342,4 +347,4 @@ function unmodelledReason(guard, what, hit, redact) {
     `interpret with certainty, so it cannot verify ${what}. Rewrite it in a simple form: ${hit.hint}.`;
 }
 
-module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason };
+module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason, isWrapperWord };

package/plugins/trailhead/hooks/mod/README.md

@@ -96,11 +96,17 @@ command file (`commands/panel.md`), because a command registered by a mod cannot
 only where no mod does (it says the panel is not available). Claude Code only: the Codex
 projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex-projection.js`).
 
-- **What it shows**: the map as a link with its destination (dim), then `Needs you · n`, `Frontier · n`,
-  `In progress · n`, `UAT · n`, `Paused · n` and `Blocked · n` (an empty group is left out). A row is `#n title`
+- **What it shows**: the map as a link with its destination (dim), then `In progress · n` (first, right under
+  the maps list), `Needs you · n`, `Frontier · n`, `UAT · n`, `Paused · n` and `Blocked · n` (an empty group is left out). A row is `#n title`
   (a link to the issue) and the type, dim. Every assigned row shows its holder as `@login`; the ticket
   in play in this session is marked `▸` in the accent and says `this session` in place of its holder;
-  blocked rows are dim. The `ownTicket` atom keeps that mark when another session's work state takes
+  blocked rows are dim. `In progress` is global for you: after the shown scope's own claimed tickets it lists your
+  open in-progress tickets (assigned to the `gh` login) of every other open map and of the whiteboard, each with a dim
+  `on map #<n> <title>` or `on whiteboard` line under it, in the map view and the Dashboard view alike (never a
+  ticket the view already lists; paused, blocked, UAT and needs-you ones stay in their own scope's groups). The login is
+  read once per host (`viewer{login}`), the tickets by one paged `gh api graphql` read of the open `trailhead:ticket`
+  issues with `filterBy:{assignee:<login>}`, in the same refresh as the view's reads; a failed or unreadable read keeps
+  the last list (the `myTickets` atom) and sets no footer error. The `ownTicket` atom keeps that mark when another session's work state takes
   over the shared file (a state stamped with another session leaves it; a missing file clears it only
   when the last state read was this session's, i.e. its own Resolve); with no own ticket the work
   state decides, as before. A ticket carrying `trailhead:paused` (set by pause, cleared by resume or a
@@ -108,7 +114,7 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   button in place of its holder (it runs like `work`, with `/trailhead:resume <n>`, which checks the
   claim); the label wins over `trailhead:blocked` and an assignee.
   A ticket carrying `trailhead:needs-you` (an autonomous run parked it for the human; a `work`/`quick` claim
-  clears it) shows once, under `Needs you`, above Frontier. The label wins over paused, UAT, blocked and an
+  clears it) shows once, under `Needs you`, between In progress and Frontier. The label wins over paused, UAT, blocked and an
   assignee. Any assignee is shown as its holder, never a button, even on a paused or blocked row. A blocked
   row with no assignee is dim with no button. Any other row gets a `work` button, never `resume`, even when
   paused: the claim clears the mark and resume would not. A
@@ -128,7 +134,8 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   across the reset too. One press at a time: another while one is held or starting is ignored. A session that ends
   while a press is held drops it. A press while the session is not in the pinned repo (a shell `cd` moved it) still
   starts: the mod cannot move the session, so it appends the pinned checkout to the verb's args as `--in=<token>`
-  (base64url of the root) and the verb `cd`s there first. With no repo pinned, or a checkout that cannot be read
+  (base64url of the root, a `.`, then base64url of the repo as `host/owner/name`) and the verb `cd`s there first;
+  if the root has moved, the verb finds the checkout again by the repo's `origin` remote. With no repo pinned, or a checkout that cannot be read
   (a removed worktree included), the press is refused with a toast before the `/clear`; both are checked again when
   a held press is sent. A refused `/clear`, or one that
   did not change the session, runs no work command. `trailhead:unverified` tickets are never listed,
@@ -185,7 +192,7 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   shown before (the view is kept), a `Maps · n` group with every open map pressable (a press leaves the
   dashboard and views that map, the active one marked `●`), and a `Whiteboard · <n> open · <m> assigned` section (counted
   over the listed tickets; `200+ open` when the list is capped): the open
-  `trailhead:ticket` + `trailhead:whiteboard` tickets as Needs you / Frontier / In progress / UAT / Paused / Blocked, with the same rows,
+  `trailhead:ticket` + `trailhead:whiteboard` tickets as In progress / Needs you / Frontier / UAT / Paused / Blocked, with the same rows,
   holders and `work` buttons (the work verb takes a whiteboard ticket as is). Unverified ones are counted only.
   Its reads replace the map's in a refresh: the whiteboard list (the GraphQL open read above), `gh issue list --label trailhead:dashboard
   --json number,url` and the maps list; a failed list keeps the last one with the footer reason, a failed index
@@ -252,19 +259,26 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   timer started on open. A write is `gh issue edit|close|create|comment|reopen|delete|transfer`, a `gh api` call on a
   `repos/.../issues` path with a write method (`-X`/`--method` POST, PATCH, PUT, DELETE) or an implicit POST
   (`-f`, `-F`, `--field`, `--raw-field`, `--input`) and no `-X GET`, or the `trailhead-issue-body.js` helper
-  (`GH_ISSUE_WRITE`); reads never refresh. Never two fetches inside `MIN_REFRESH_MS`: a request inside the floor
+  (`GH_ISSUE_WRITE`); reads never refresh. Never two fetches inside `MIN_REFRESH_MS` (save the turn-end read below): a request inside the floor
   keeps one trailing refresh for the rest of it. A write that reads at once also arms that trailing refresh, so one
   more read follows when the floor ends, after the search index (the history) caught up; a burst of writes still costs one
-  read per floor plus one trailing. The host drops a refused timer without a word (a refused `every` period ends
+  read per floor plus one trailing, and one more when the turn ends after it. The host drops a refused timer without a word (a refused `every` period ends
   the interval), so the slow timer is kept with its due time: past it by more than `TIMER_GRACE_MS` it is held dead
-  and the next trigger starts it again (`isTimerLate`). A read asked while the pane is undrawn is dropped; a render
+  and the next trigger starts it again (`isTimerLate`). The trailing refresh is kept with its due time the same way:
+  a dropped one is replaced by the next trigger, and a render past its due time by more than `TIMER_GRACE_MS` asks
+  for the read at once. A turn end that follows a tracker write newer than the last read start reads at once,
+  floor or not (one extra read per turn at most, never without a write), so the final state shows with no timer
+  involved; it leaves an armed trailing refresh alone, so the read after the search index caught up still follows.
+  A read asked while the pane is undrawn is dropped; a render
   whose list (with no error) is older than `TIMER_MS + TIMER_GRACE_MS` asks for a read at once, as an empty view does.
 - **Auto-open**: once, in fullscreen (`e.viewport.isFullscreen === true` in the `AbovePrompt` render),
   when a map is active. Never on the main screen, never again after the pane was opened or closed
   by the person (a press on the `close` button counts as closing it). The open runs from a zero-delay timer because a render may not write state.
   Being unasked, it waits undrawn below 144 columns (`isPlaced: false`), typical of a fresh session; `/trailhead:panel`
   then opens it again as the person's request (drawn at any width) instead of closing it, and closes it only when even
-  that leaves it undrawn (no surface places panes).
+  that leaves it undrawn (the attached surfaces place no panes). With no surface attached yet (`no-surface`, the start of a session)
+  the pane stays open and the command answers that it will open once the screen is ready, again on every repeat; the
+  pane's first render on the surface that attaches asks for its read.
 - **Constants** (`map-pane.tsx`): `PANE_ID = 'trailhead-map'`, `PANE_TITLE = 'Map'`,
   `MIN_REFRESH_MS = 15_000`, `TIMER_MS = 180_000`, `GH_TIMEOUT_MS = 20_000`, `TIMER_GRACE_MS = 30_000`,
   `PANEL_COMMAND = 'trailhead:panel'`, `MAPS_LIMIT = MAPS_READ_LIMIT = 100` (`MAPS_LIMIT` not exported); `worktree-porcelain.ts`: `MAX_FAILURES = 3` (shared by the work-state lookup and the run scan); `auto-run-view.ts`: `RESUME_HINT`; `map-pane-view.ts`: `MAPS_READ_LIMIT = 100`, `LIST_LIMIT = 200`, `HISTORY_LIMIT = 5000`.