Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

20.7 KB
Raw Blame
/**
 * `trail init`'s look-back, start to end (design 4.1 to 4.9): start the
 * no-model look-back in a worker while init wires the repo, then show what
 * it found and keep only what the person picks.
 *
 * - The person at their own terminal (`personAtTerminal().ok`): the naming
 *   call (and phase 0's PR-review read) may run, unless `--plain` or
 *   `TRAIL_NO_LOOK_BACK` (0 rule 4); then the review screen, whose keys keep.
 * - An agent (`agentRun`: CLAUDECODE, or a claude or pty-wrapper ancestor):
 *   never a `claude` process, even a stand-in; the relay with plain names
 *   for the agent to show as written, and `pending` for `trail keep` (P2).
 * - The person's own script (no TTY, not an agent): the same list without
 *   the agent's line (B9). `--yes` there keeps only the person's own typed
 *   preferences; an agent's `--yes` keeps nothing (R25, P37).
 *
 * Phase 0's find call, which sent typed messages to the model, is gone
 * (R60, D87): `lookBackOffThread` replaces it, skills on or off.
 *
 * #662's team rows share the screen, first and ticked: what reviewers made
 * authors change on merged PRs, tied to code that exists, and what Claude
 * Code keeps about the repo on this machine (no model). With no screen they
 * are kept as #662 keeps them, and the agent is told to ask about the commit
 * (D184).
 */
import { createHash } from 'node:crypto';
import { anchoredReviews, finishReviewRead, beginReviewRead, type ReviewFinding, type ReviewRead, type ReviewResult } from '../notes/pr-reviews.js';
import { finishMemoryRead, memoryCandidates, offeredBefore, type MemoryCandidate } from '../notes/memory-notes.js';
import type { Note } from '../notes/notes.js';
import { repoPlace } from '../notes/home.js';
import { readSettings } from '../skills/settings.js';
import { nameTaken, personAtTerminal, type PersonCheck, type PersonDeps } from '../skills/store.js';
import { countBucket, durationBucket } from '../telemetry/contract.js';
import { track } from '../telemetry/track.js';
import { candidateId, pickFive } from './candidates.js';
import { whyLine } from './claude-call.js';
import { lookBackOffThread } from './discover-worker.js';
import { newRunId, readInitRecord, uncompiledOf, updateInitRecord, type InitRun } from './init-record.js';
import { keepItems, prefLine, type KeepResult } from './keep.js';
import { leadWords } from './keep-answer.js';
import { lookBackDue, lookBackOff, markLookedBack, norm } from './look-back.js';
import type { LookBackResult } from './look-back-mine.js';
import type { LookBack } from './types.js';
import { NAME_MODEL, nameItems, type Named } from './name-call.js';
import { afterKeepLines, INIT_COPY, numbered, relayLines, repoNameOf, yesLine, type ScreenFacts } from './review-screen.js';
import { runScreen } from './review-tty.js';
import type { InitCandidate, InitItem } from './types.js';

/** An agent ran init: CLAUDECODE set, or a claude or pty-wrapper ancestor. A script the person runs with no TTY is !agentRun(env) (R17). */
export function agentRun(env: NodeJS.ProcessEnv, deps: PersonDeps = {}, person?: PersonCheck): boolean {
  if (env.CLAUDECODE !== undefined) return true;
  return (person ?? personAtTerminal(env, deps)).claudeAncestor;
}

/** 0 rule 4: the person at their own terminal, the look-back on, and no `--plain`. Never starts anything itself. */
export function mayCallClaude(env: NodeJS.ProcessEnv, flags: { plain: boolean }, deps: PersonDeps = {}, person?: PersonCheck): boolean {
  if (flags.plain || lookBackOff(env)) return false;
  return (person ?? personAtTerminal(env, deps)).ok;
}

export interface LookBackReads {
  lb: Promise<LookBackResult> | null;
  reviews: ReviewRead | null;
  /** #662: Claude Code's memory notes about the repo, fit for the team. Read with no model, look-back due or not. */
  memory: MemoryCandidate[];
  person: PersonCheck;
  agent: boolean;
  model: boolean;
  plain: boolean;
  skills: boolean;
  env: NodeJS.ProcessEnv;
  started: number;
}

/** Agent runs stop reading at 100 s so the tool call ends inside Claude Code's 120 s; the person's at 300 s (3.6). */
const AGENT_CAP_MS = 100_000;
const PERSON_CAP_MS = 300_000;

/** Start the look-back and the PR-review read; the lines to print now, before anything finishes. */
export function beginLookBack(repo: string, opts: { env?: NodeJS.ProcessEnv; plain?: boolean; again?: boolean; deps?: PersonDeps } = {}):
  { reads: LookBackReads; lines: string[] } {
  const env = opts.env ?? process.env;
  const person = personAtTerminal(env, opts.deps ?? {});
  const agent = agentRun(env, opts.deps ?? {}, person);
  const plain = opts.plain === true;
  const model = !agent && mayCallClaude(env, { plain }, opts.deps ?? {}, person);
  const skills = readSettings(env).skills === 'on';
  const memory = memoryRows(repo, env.HOME);
  const reads: LookBackReads = { lb: null, reviews: null, memory, person, agent, model, plain, skills, env, started: Date.now() };
  if (lookBackOff(env) || !(opts.again || lookBackDue(repo, env))) return { reads, lines: [] };
  reads.lb = lookBackOffThread(repo, { env, capMs: agent ? AGENT_CAP_MS : PERSON_CAP_MS, skills });
  const lines = ['· looking back at your past Claude Code sessions here (about a minute)'];
  // The PR-review read is phase 0's second call: only where the naming call may run (0 rule 4).
  reads.reviews = model ? beginReviewRead(repo, env) : null;
  if (reads.reviews) lines.push("· reading review comments on this repo's merged PRs for what reviewers keep flagging");
  return { reads, lines };
}

/** #662's memory candidates, or none when they can't be read: init never stops for them. */
function memoryRows(repo: string, home?: string): MemoryCandidate[] {
  try {
    return memoryCandidates(repo, { ...(home ? { home } : {}), offered: offeredBefore(repo) });
  } catch {
    return [];
  }
}

const GUARD_DESC: Record<string, string> = { 'timeout-missing': 'this Mac has no timeout', 'git-https-auth': 'push to this repo over SSH' };

/**
 * A PR-review finding (D24) as a team row: its words are model text, so it is shown on the screen only, never
 * relayed. Only the findings tied to code that exists (#662's anchoredReviews), ticked: the team's start ticked.
 */
function reviewItems(anchored: ReviewFinding[], repoKey: string, closed: Set<string>): InitItem[] {
  return anchored.map((f, n) => {
    const key = `review:${createHash('sha256').update(norm(f.title)).digest('hex').slice(0, 16)}`;
    return {
      id: candidateId('review', key), kind: 'review' as const, key, plainName: '', nameWords: leadWords(f.title),
      count: { days: f.prs.length, from: f.last, to: f.last }, scope: 'repo' as const, applies: repoKey, typed: false, ticked: true,
      review: { prs: f.prs }, evidence: [], rank: n + 1, n: 0, title: f.title, description: '',
    };
  }).filter((c) => !closed.has(c.id));
}

/** #662's memory candidates as team rows, ticked. Never relayed: with no screen, #662 keeps them itself. */
function memoryItems(memory: MemoryCandidate[], repoKey: string): InitItem[] {
  return memory.map((c, n) => {
    const key = `claude:${createHash('sha256').update(c.path).digest('hex').slice(0, 16)}`;
    return {
      id: candidateId('claude', key), kind: 'claude' as const, key, plainName: '', nameWords: leadWords(c.title),
      count: { days: 0, from: c.updated, to: c.updated }, scope: 'repo' as const, applies: repoKey, typed: false, ticked: true,
      memory: { path: c.path }, evidence: [], rank: n + 1, n: 0, title: c.title, description: '',
    };
  });
}

const isTeam = (i: Pick<InitItem, 'kind'>) => i.kind === 'review' || i.kind === 'claude';

/** For a run with no look-back (not due, or off), so #662's team rows can still be shown. */
const NO_LOOK_BACK: LookBack = {
  sessions: [], skipped: [], days: 0, from: null, to: null, parent: 0, candidates: [], alreadyKept: { here: 0, elsewhere: [] }, howtos: [], ms: 0, errors: [],
};

/** What #662's keeps saved with no screen, for init to say in #662's words (cli.ts). */
export interface TeamKept {
  fromReviews: { result: ReviewResult; saved: Note[]; kept: ReviewFinding[]; offered: number } | null;
  fromMemory: { saved: Note[]; offered: number } | null;
}

/** The shown items with their titles: the naming call's or the plain name, a guardrail's fixed words, the person's line read now. */
function itemsOf(picked: Array<InitCandidate & { n: number }>, named: Named, env: NodeJS.ProcessEnv): InitItem[] {
  const out: InitItem[] = [];
  for (const c of picked) {
    if (c.kind === 'skill') {
      const nm = named.names[c.id];
      out.push({ ...c, title: nm?.title ?? c.plainName, description: nm?.description ?? c.skill?.compiled.description ?? '' });
    } else if (c.kind === 'guardrail') {
      out.push({ ...c, title: c.plainName, description: GUARD_DESC[c.guardrail?.cls ?? ''] ?? '' });
    } else if (c.kind === 'preference') {
      const line = prefLine(c, env);
      if (line) out.push({ ...c, title: line, description: '' });
    }
  }
  // Numbers stay 1..k with no gap, by kind (a preference whose line is gone drops out).
  return out.map((i, k) => ({ ...i, n: k + 1 }));
}

/**
 * `team`: #662's team rows saved into `.trail/learnings/`, for the agent's commit ask; `teamKept`: what they were, with
 * no screen. `read`: what was looked at, for `init --pair` and `--connect` to count: the past sessions, and the merged
 * PRs (null when the PR reviews weren't read). `skills`: the skills the look-back found this run, each kept (or not) on
 * this machine only, for the pair page to list by name and day count: never their steps.
 */
export interface LookBackDone { kept: number; inRepo: boolean; team: number; teamKept?: TeamKept; read?: { sessions: number; prs: number | null }; skills?: FoundSkill[] }

/** A skill the look-back found, as `init --pair` names it to Trail's page: its name and title, and on how many days it came up. */
export interface FoundSkill { id: string; name: string; title: string; days: number }

/**
 * Wait for the reads, show what they found (screen, relay or the script's list), keep what the person picks, and
 * write the init record. `io` is the person's terminal for the screen. #662's team rows come first on the screen;
 * with no screen they are kept as #662 keeps them.
 */
export async function finishLookBack(repo: string, reads: LookBackReads,
  mode: { yes: boolean; say: (line: string) => void; io?: { stdin: NodeJS.ReadStream; stdout: NodeJS.WriteStream }; now?: Date; verbose?: boolean }): Promise<LookBackDone> {
  const none: LookBackDone = { kept: 0, inRepo: false, team: 0 };
  if (!reads.lb && !reads.memory.length) return none;
  const { env, agent, person } = reads;
  const say = mode.say;
  const now = mode.now ?? new Date();
  const looked = reads.lb !== null;
  let lb: LookBackResult = NO_LOOK_BACK;
  if (reads.lb) {
    let settled = false;
    void reads.lb.then(() => (settled = true));
    await Promise.resolve();
    if (!settled) say('· still looking back at your past sessions…');
    lb = await reads.lb;
  }
  const repoKey = repoPlace(repo, env).key;
  const record = readInitRecord(repoKey, env);
  const deferred = new Set(record.deferred);
  // An agent's init never shows what the person put off in their own terminal (4.5, B5).
  const found = lb.candidates.filter((c) => !(agent && deferred.has(c.id)));
  const first = pickFive(found);
  const skillsToName = first.filter((c) => c.kind === 'skill');
  const modelWhy = agent ? 'agent' : reads.plain ? 'plain' : !person.tty ? 'no-tty' : lookBackOff(env) ? 'off' : !person.ok ? 'not-person' : !skillsToName.length ? 'no-skills' : null;
  const namedP: Promise<Named> = reads.model && skillsToName.length
    ? nameItems(skillsToName, env, { taken: (n) => nameTaken(n, { repoKeys: [repoKey], checkout: repo, env }) !== null })
    : Promise.resolve({ names: {}, model: 'none', why: null, sentItems: 0, tokens: 0 });
  let reviewResult: ReviewResult | null = null;
  if (reads.reviews) {
    if (!reads.reviews.done) say('· still reading PR reviews…');
    reviewResult = await reads.reviews.result.catch(() => null);
  }
  const named = await namedP;
  const read = { sessions: lb.sessions.length, prs: reviewResult ? reviewResult.prs : null };
  // The look-back's own five, numbered 1..k for the relay and `trail keep`.
  const items = itemsOf(numbered(first), named, env);
  const skills: FoundSkill[] = items.filter((i) => i.kind === 'skill').map((i) => ({ id: i.id, name: i.plainName, title: i.title, days: i.count.days }));
  // #662's team rows: only findings tied to code that exists, and the memory notes; never relayed.
  const anchored = reviewResult ? anchoredReviews(repo, reviewResult.findings) : [];
  const team = [...reviewItems(anchored, repoKey, new Set([...record.closed, ...record.runs.flatMap((r) => r.kept)])), ...memoryItems(reads.memory, repoKey)];
  const s = readSettings(env);
  const facts: ScreenFacts = {
    lookBack: lb, model: named.model, why: named.why, tokens: named.tokens, calls: (named.sentItems ? 1 : 0) + (reads.reviews ? 1 : 0),
    offers: s.offers, offersOffAt: s.offersOffAt, repoName: repoNameOf(repoKey), agent, skills: reads.skills,
    sentSkills: named.sentItems, reviewsRead: reviewResult?.read ?? 0, ...(named.said ? { whySaid: named.said } : {}),
    ...(looked ? {} : { lookedBack: false }),
  };
  if (reviewResult?.why && reviewResult.why !== named.why) say(`· ${whyLine({ why: reviewResult.why, ...(reviewResult.said ? { said: reviewResult.said } : {}) }, 'PR reviews')}`);

  // D135 (3): jobs that met the bar but didn't compile, as codes; said with --verbose.
  const uncompiled = uncompiledOf((lb.refused ?? []).map((u) => ({ job: u.job, days: u.days, why: u.why.split(', ') })));
  if (mode.verbose) for (const u of uncompiled) say(`· not offered as a skill: ${u.job}, on ${u.days} day${u.days === 1 ? '' : 's'} (${u.why.join(', ')})`);
  // One screen: the team rows first, then the look-back's items, numbered on from them.
  const shown = [...team, ...items].map((i, k) => ({ ...i, n: k + 1 }));
  const screen = person.ok && !agent && !mode.yes && !!mode.io && shown.length > 0;
  const run: InitRun = {
    id: newRunId(), at: now.toISOString(), by: agent ? 'agent' : person.ok ? 'person' : 'script', screen: screen ? 'tty' : agent ? 'relay' : 'list',
    reads: { sessions: lb.sessions.length, days: lb.days, from: lb.from, to: lb.to, parent: lb.parent, read: lb.sessions.map((x) => x.sh), skipped: lb.skipped,
      ...(uncompiled.length ? { uncompiled } : {}) },
    model: named.sentItems ? NAME_MODEL : 'none', modelWhy: named.why ?? modelWhy, calls: facts.calls, tokens: named.tokens, ms: lb.ms,
    shown: (screen ? shown : items).filter((i) => i.kind !== 'claude').map((i) => i.id), kept: [], closed: [], deferred: [],
  };
  if (looked) {
    updateInitRecord(repoKey, (r) => {
      r.runs.push(run);
    }, env);
  }
  const place = { dir: repo, repoKey, runId: run.id };
  const tele = (outcome: string, picked: number) => {
    if (!looked) return;
    track('cold_start', {
      source: 'sessions', outcome, sessions_bucket: countBucket(lb.sessions.length), offered_bucket: countBucket(items.length),
      picked_bucket: countBucket(picked), duration_bucket: durationBucket(Date.now() - reads.started), model: run.model,
    }, { repo });
  };
  /** #662's two keeps, each with its own answer: the review rows and the memory rows picked, none, or null (asked again). */
  const keepTeam = async (pick: ((rows: InitItem[]) => InitItem[]) | null | 'auto') => {
    const choose = (rows: InitItem[]) => (pick === null ? null : pick === 'auto' ? undefined : pick(rows));
    const reviewRows = team.filter((i) => i.kind === 'review');
    const memoryRows = team.filter((i) => i.kind === 'claude');
    let fromReviews: TeamKept['fromReviews'] = null;
    if (reads.reviews) {
      const chosen = choose(reviewRows);
      const titles = new Set((chosen ?? []).map((i) => i.title));
      // anchoredReviews gives the same findings for the same repo: matched by title, as shown.
      const r = await finishReviewRead(repo, reads.reviews, chosen === undefined ? undefined : async (f) => (chosen === null ? null : f.filter((x) => titles.has(x.title))));
      fromReviews = { ...r, offered: anchored.length };
    }
    let fromMemory: TeamKept['fromMemory'] = null;
    if (reads.memory.length) {
      const chosen = choose(memoryRows);
      const paths = new Set((chosen ?? []).map((i) => i.memory?.path));
      const r = await finishMemoryRead(repo, reads.memory, chosen === undefined ? undefined : async (c) => (chosen === null ? null : c.filter((x) => paths.has(x.path))));
      fromMemory = { saved: r.saved, offered: reads.memory.length };
    }
    const saved = [...(fromReviews?.saved ?? []), ...(fromMemory?.saved ?? [])];
    return { fromReviews, fromMemory, team: saved.filter((n) => n.scope === 'repo').length };
  };

  if (!shown.length) {
    if (looked) {
      for (const l of relayLines([], facts)) say(l);
      if (!reads.skills) say(INIT_COPY.skillsOff!);
      if (!lb.errors.length) markLookedBack(repo, now, env);
    }
    if (reads.reviews) await finishReviewRead(repo, reads.reviews, async () => []);
    tele('none_found', 0);
    return { ...none, read, skills };
  }

  if (screen) {
    const answer = await runScreen(shown, facts, mode.io!, { repoKey, env });
    const final = shown.map((i) => ({ ...i, ...(answer.scopes[i.n] ?? {}) }));
    let result: KeepResult = { kept: [], notKept: [], refused: [] };
    let teamSaved = 0;
    if (answer.how === 'esc') {
      if (looked) {
        updateInitRecord(repoKey, (r) => {
          const ids = items.map((i) => i.id);
          r.deferred = [...new Set([...r.deferred, ...ids])];
          const me = r.runs.find((x) => x.id === run.id);
          if (me) me.deferred = ids;
          r.pending = [];
          r.pendingFrom = null;
          r.handedAt = null;
          r.handover = null;
        }, env);
      }
      await keepTeam(null);
      tele('cancelled', 0);
    } else {
      const ticked = new Set(answer.how === 'enter' ? answer.ticked : []);
      const picked = final.filter((i) => ticked.has(i.n));
      const own = final.filter((i) => !isTeam(i));
      result = own.length ? keepItems(picked.filter((i) => !isTeam(i)), own, 'tty', env, now, place) : result;
      const keptTeam = picked.filter(isTeam);
      teamSaved = (await keepTeam((rows) => rows.filter((r) => keptTeam.some((k) => k.id === r.id)))).team;
      result = { ...result, kept: [...keptTeam, ...result.kept], notKept: final.filter((i) => !picked.includes(i)) };
      const keptReviews = keptTeam.filter((i) => i.kind === 'review');
      if (keptReviews.length || final.some((i) => i.kind === 'review' && !picked.includes(i))) {
        updateInitRecord(repoKey, (r) => {
          r.closed = [...new Set([...r.closed, ...final.filter((i) => i.kind === 'review' && !picked.includes(i)).map((i) => i.id)])];
          const me = r.runs.find((x) => x.id === run.id);
          if (me) me.kept = [...new Set([...me.kept, ...keptReviews.map((i) => i.id)])];
        }, env);
      }
      if (looked) markLookedBack(repo, now, env);
      tele('found', result.kept.filter((i) => !isTeam(i)).length);
    }
    for (const l of afterKeepLines({ ...result, how: answer.how }, facts)) say(l);
    return { kept: result.kept.length, inRepo: result.kept.some((i) => i.scope === 'repo' || isTeam(i)), team: teamSaved, read, skills };
  }

  // No screen: the relay (agent) or the script's list for the look-back's items. A PR-review finding is model text
  // and is never relayed; #662 keeps the team rows itself and says what it kept.
  let list = items;
  let kept = 0;
  if (mode.yes && !agent && list.length) {
    const own = list.filter((i) => i.kind === 'preference' && i.typed && !deferred.has(i.id));
    const r = keepItems(own, list, 'yes', env, now, place);
    kept = r.kept.length;
    say(yesLine(list, false));
    const gone = new Set(r.kept.map((i) => i.id));
    list = list.filter((i) => !gone.has(i.id)).map((i, k) => ({ ...i, n: k + 1 }));
  } else if (mode.yes && agent && list.length) {
    say(yesLine(list, true));
  }
  // The look-back found nothing to keep: its found line and why, as with no team rows.
  if (looked && !items.length) {
    for (const l of relayLines([], facts)) say(l);
    if (!lb.errors.length) markLookedBack(repo, now, env);
  }
  const fromTeam = await keepTeam('auto');
  if (list.length) {
    updateInitRecord(repoKey, (r) => {
      r.pending = list.map((i) => ({ ...i }));
      r.pendingFrom = run.id;
      r.shownAt = now.toISOString();
      r.handedAt = null;
      r.handover = null;
    }, env);
    for (const l of relayLines(list, facts)) say(l);
  }
  if (looked && !reads.skills) say(INIT_COPY.skillsOff!);
  tele('relayed', kept);
  const teamKept = (fromTeam.fromReviews?.saved.length ?? 0) + (fromTeam.fromMemory?.saved.length ?? 0);
  return { kept: kept + teamKept, inRepo: fromTeam.team > 0, team: fromTeam.team, teamKept: { fromReviews: fromTeam.fromReviews, fromMemory: fromTeam.fromMemory }, read, skills };
}