Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
25.9 KB
Raw Blame
/**
 * skillpack/safe-update.ts — `gbrain skillpack reference <name>|--all --update-untouched`.
 *
 * Takes upstream on installed skills the user never edited, one whole skill
 * at a time. A skill's closure is every file under its bundle dir plus any
 * shared dependency it lacks; paired sources outside the skills root are
 * never written (they are reported).
 *
 * Classification, per file (the install's recorded base always wins):
 *   unchanged    already equals the bundle
 *   absent       missing and gbrain never recorded it (a new file)
 *   untouched    equals its recorded base
 *   local_edits  differs from its recorded base (even when it equals a past
 *                release), or has no base and matches no released version,
 *                or was deleted after gbrain recorded it
 *   historical   no base, equals a released version (needs --accept-historical)
 *   no_history   no base, and the released-version history has no entry
 * A skill is updatable only when it is not pinned, the history verified,
 * and every changed file is absent, untouched, or historical with
 * --accept-historical. Anything else skips the whole skill with a reason.
 *
 * Commit protocol: stage the closure in the skills root and validate it,
 * write the journal (update-journal.ts), back up each file, rehash it right
 * before its rename (abandon the skill on any change since classification),
 * then run conformance, the trigger check and the resolver check. A conflict,
 * an error or a failed check rolls back the files already renamed that still
 * hold the update's bytes. Bases are recorded only after a skill commits.
 * The caller holds the workspace writer lock; state writes take the shared
 * state lock (state.ts updateState), so the order is always workspace, state.
 */
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'fs';
import { basename, dirname, join, relative, resolve, sep } from 'path';

import { bundledSkillSlugs, enumerateScaffoldEntries, loadBundleManifest, type BundleManifest } from './bundle.ts';
import { loadVerifiedSkillsLockHistory, type VerifiedSkillsLockHistory } from '../skills-integrity.ts';
import { loadState, updateState, withSkillBases, type InstalledSkillRecord } from './state.ts';
import { unifiedDiff } from './diff-text.ts';
import { redactFindings } from '../secret-scan.ts';
import { parseSkillFrontmatter } from '../skill-frontmatter.ts';
import { loadSkillTriggerIndex } from '../skill-trigger-index.ts';
import { checkResolvable, type ResolvableIssue } from '../check-resolvable.ts';
import { OperationError } from '../ops/contract.ts';
import { confinedSkillChildWrite } from './writer-guard.ts';
import { relativeEscapesRoot } from '../path-confine.ts';
import {
  backupFile, backupsRoot, hashTarget, newJournalId, pendingJournals, planRestore, pruneJournals, readJournal, sha256, undoFile, writeJournal,
  type Journal, type JournalFile, type JournalSkill, type RestorePlanFile,
} from './update-journal.ts';

export const DIFF_LINE_CAP = 200;
const STAGE_PREFIX = '.gbrain-skillpack-stage-';

export type FileState = 'unchanged' | 'absent' | 'untouched' | 'historical' | 'local_edits' | 'no_history';
export type SkipReason = 'pinned' | 'history_unverified' | 'unsafe_target' | 'local_edits' | 'no_history' | 'historical_only';

export interface ClassifiedFile {
  rel: string;
  source: string;
  post: string;
  pre: string | null;
  base: string | null;
  sharedDep: boolean;
  state: FileState;
}

export interface SkillOutcome {
  slug: string;
  result: 'updated' | 'would_update' | 'current' | 'skipped' | 'failed' | 'not_installed';
  reason?: SkipReason;
  pinned: boolean;
  /** Files the update writes (or would write). */
  changes: string[];
  /** Files with no base that match only a released version. */
  historical: string[];
  notes: string[];
  diffs?: Array<{ rel: string; diff: string; truncated: boolean }>;
  /** On failure: files this run renamed, and those it could not roll back because they changed again. */
  touched?: string[];
  rollback_skipped?: string[];
  failure?: string;
  files: ClassifiedFile[];
}

export interface UpdateResult {
  dry_run: boolean;
  skills_root: string;
  history: { verified: boolean; reason?: string };
  journal: string | null;
  pending_journals: string[];
  summary: Record<SkillOutcome['result'], number>;
  skills: SkillOutcome[];
  restore_command: string | null;
}

export interface UpdateOptions {
  gbrainRoot: string;
  /** Absolute skills root (see skillsRootKey). */
  skillsRoot: string;
  /** Skill slugs, or null for every bundled skill. */
  slugs: string[] | null;
  dryRun?: boolean;
  acceptHistorical?: boolean;
  noDiff?: boolean;
  statePath?: string;
  backups?: string;
  /** Post-rename checks; returns problems (empty = pass). Defaults to conformance + triggers + resolver. */
  validate?: (skillsRoot: string, slug: string) => string[];
  hooks?: { beforeRename?: (rel: string) => void; afterRename?: (rel: string) => void };
}

/** The key a skills root (or a file under it) is recorded under: the realpath of its deepest existing ancestor plus the rest. */
export function skillsRootKey(dir: string): string {
  const missing: string[] = [];
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- skillsRootKey only normalizes a caller-given skills root into its realpath key; no read or write
  let current = resolve(dir);
  for (;;) {
    try {
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same: realpath key of the deepest existing ancestor plus its missing basenames
      return join(realpathSync(current), ...missing.reverse());
    } catch {
      const parent = dirname(current);
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same: fallback key when no ancestor resolves
      if (parent === current) return resolve(dir);
      missing.push(basename(current));
      current = parent;
    }
  }
}

function fileState(pre: string | null, post: string, base: string | null, history: VerifiedSkillsLockHistory, rel: string): FileState {
  if (pre === post) return 'unchanged';
  if (base !== null) return pre === base ? 'untouched' : 'local_edits';
  if (pre === null) return 'absent';
  const released = history.ok ? history.history.files[rel] : undefined;
  if (!released?.length) return 'no_history';
  return released.includes(pre) ? 'historical' : 'local_edits';
}

function boundedRedactedDiff(local: Buffer, bundle: Buffer, rel: string): { diff: string; truncated: boolean } {
  if (local.includes(0) || bundle.includes(0)) return { diff: `Binary file ${rel} differs (local ${local.length} B, bundle ${bundle.length} B).\n`, truncated: false };
  const text = redactFindings(unifiedDiff(local.toString('utf-8'), bundle.toString('utf-8'), { oldPath: `a/${rel}`, newPath: `b/${rel}` })).text;
  const lines = text.split('\n');
  if (lines.length <= DIFF_LINE_CAP) return { diff: text, truncated: false };
  return { diff: lines.slice(0, DIFF_LINE_CAP).join('\n') + `\n... ${lines.length - DIFF_LINE_CAP} more line(s)\n`, truncated: true };
}

export interface ClassifyContext {
  gbrainRoot: string;
  skillsRoot: string;
  manifest: BundleManifest;
  history: VerifiedSkillsLockHistory;
  records: Record<string, InstalledSkillRecord>;
  acceptHistorical: boolean;
  noDiff: boolean;
}

export function classifySkill(ctx: ClassifyContext, slug: string): SkillOutcome {
  const record = ctx.records[slug];
  const files: ClassifiedFile[] = [];
  const notes: string[] = [];
  let unsafe: string | null = null;
  for (const entry of enumerateScaffoldEntries({ gbrainRoot: ctx.gbrainRoot, skillSlug: slug, manifest: ctx.manifest })) {
    if (entry.pairedSource) {
      notes.push(`paired source ${entry.relWorkspaceTarget} lives outside the skills root and is never written here; compare it with gbrain skillpack reference ${slug}`);
      continue;
    }
    const rel = entry.relWorkspaceTarget.replace(/^skills\//, '');
    let pre: string | null;
    try {
      pre = hashTarget(confinedSkillChildWrite(ctx.skillsRoot, rel, { dryRun: true }));
    } catch (err) {
      unsafe = `${rel}: ${(err as Error).message}`;
      continue;
    }
    if (entry.sharedDep && pre !== null) continue;
    const post = sha256(readFileSync(entry.source));
    const base = record?.files[rel] ?? null;
    files.push({ rel, source: entry.source, post, pre, base, sharedDep: entry.sharedDep, state: fileState(pre, post, base, ctx.history, rel) });
  }
  if (unsafe) notes.push(unsafe);
  const outcome: SkillOutcome = {
    slug, result: 'current', pinned: record?.pinned === true, changes: [], historical: files.filter(f => f.state === 'historical').map(f => f.rel), notes, files,
  };
  const skillMd = files.find(f => f.rel === `${slug}/SKILL.md`);
  if (!Object.keys(record?.files ?? {}).length && skillMd?.pre === null) return { ...outcome, result: 'not_installed', historical: [] };
  const changed = files.filter(f => f.state !== 'unchanged');
  outcome.changes = changed.map(f => f.rel);
  if (changed.length === 0 && !unsafe) return outcome;
  const reason: SkipReason | undefined = outcome.pinned ? 'pinned'
    : !ctx.history.ok ? 'history_unverified'
    : unsafe ? 'unsafe_target'
    : changed.some(f => f.state === 'local_edits') ? 'local_edits'
    : changed.some(f => f.state === 'no_history') ? 'no_history'
    : outcome.historical.length && !ctx.acceptHistorical ? 'historical_only'
    : undefined;
  if (!reason) return { ...outcome, result: 'would_update' };
  outcome.result = 'skipped';
  outcome.reason = reason;
  if (!ctx.noDiff && reason !== 'pinned') {
    outcome.diffs = changed.filter(f => f.pre !== null).map(f => ({
      rel: f.rel, ...boundedRedactedDiff(readFileSync(confinedSkillChildWrite(ctx.skillsRoot, f.rel, { dryRun: true })), readFileSync(f.source), f.rel),
    }));
  }
  return outcome;
}

function issueKey(issue: ResolvableIssue): string {
  return `${issue.type}|${issue.skill}|${issue.message}`;
}

function mentionsSkill(issue: ResolvableIssue, slug: string): boolean {
  return issue.skill === slug || issue.skill.includes(`${slug}/`) || issue.skill.split(/,\s*/).includes(slug);
}

/**
 * Conformance, trigger and resolver checks. Built before the first rename:
 * resolver errors present then are the baseline and do not count against a
 * skill (a resolver that cannot run at all is not checked).
 */
export function defaultValidator(skillsRoot: string): (root: string, slug: string) => string[] {
  let baseline: Set<string> | null;
  try {
    baseline = new Set(checkResolvable(skillsRoot).errors.map(issueKey));
  } catch {
    baseline = null;
  }
  return (root, slug) => {
    const problems: string[] = [];
    const content = readFileSync(confinedSkillChildWrite(root, `${slug}/SKILL.md`, { dryRun: true }), 'utf-8');
    const fm = content.startsWith('---') ? parseSkillFrontmatter(content) : null;
    if (!fm?.name) problems.push(`conformance: ${slug}/SKILL.md has no frontmatter with a name`);
    if (fm?.triggers?.length && !loadSkillTriggerIndex(root).some(e => e.skillPath === `${slug}/SKILL.md` || e.skillPath.endsWith(`/${slug}/SKILL.md`))) {
      problems.push(`trigger check: ${slug} declares triggers but the trigger index does not route to it`);
    }
    if (baseline !== null) {
      try {
        for (const issue of checkResolvable(root).errors) {
          if (mentionsSkill(issue, slug) && !baseline!.has(issueKey(issue))) problems.push(`resolver check: ${issue.message}`);
        }
      } catch (err) {
        problems.push(`resolver check failed: ${(err as Error).message}`);
      }
    }
    return problems;
  };
}

function removeStaleStages(skillsRoot: string): void {
  if (!existsSync(skillsRoot)) return;
  for (const name of readdirSync(skillsRoot)) {
    if (name.startsWith(STAGE_PREFIX)) rmSync(confinedSkillChildWrite(skillsRoot, name, { dryRun: true }), { recursive: true, force: true });
  }
}

interface ApplyContext {
  opts: UpdateOptions;
  journal: Journal;
  backups: string;
  validate: (root: string, slug: string) => string[];
}

function rollback(ctx: ApplyContext, renamed: JournalFile[]): string[] {
  const left: string[] = [];
  for (const file of [...renamed].reverse()) {
    try {
      if (!undoFile(ctx.journal.id, ctx.opts.skillsRoot, file, ctx.backups)) left.push(file.rel);
    } catch {
      left.push(file.rel);
    }
  }
  return left;
}

async function applySkill(ctx: ApplyContext, outcome: SkillOutcome, js: JournalSkill): Promise<SkillOutcome> {
  const { skillsRoot } = ctx.opts;
  const changed = outcome.files.filter(f => f.state !== 'unchanged');
  const fail = (failure: string, status: JournalSkill['status'], renamed: JournalFile[] = []): SkillOutcome => {
    const rollbackSkipped = renamed.length ? rollback(ctx, renamed) : [];
    js.status = status;
    js.reason = failure;
    writeJournal(ctx.journal, ctx.backups);
    return { ...outcome, result: 'failed', failure, touched: renamed.map(f => f.rel), rollback_skipped: rollbackSkipped };
  };
  mkdirSync(skillsRoot, { recursive: true });
  const stage = mkdtempSync(confinedSkillChildWrite(skillsRoot, STAGE_PREFIX, { dryRun: true }));
  try {
    const staged: string[] = [];
    for (const [i, f] of changed.entries()) {
      const bytes = readFileSync(f.source);
      if (sha256(bytes) !== f.post) return fail(`bundle file ${f.rel} changed during the run`, 'abandoned');
      if (f.rel === `${outcome.slug}/SKILL.md` && !parseSkillFrontmatter(bytes.toString('utf-8'))?.name) {
        return fail(`staged ${f.rel} has no frontmatter with a name`, 'abandoned');
      }
      const path = confinedSkillChildWrite(stage, String(i), { dryRun: true });
      writeFileSync(path, bytes);
      staged.push(path);
    }
    let fresh: InstalledSkillRecord | undefined;
    try {
      fresh = loadState({ statePath: ctx.opts.statePath }).roots?.[skillsRoot]?.[outcome.slug];
    } catch (err) {
      return fail(`the state file cannot be read: ${(err as Error).message}`, 'abandoned');
    }
    if (fresh?.pinned || changed.some(f => (fresh?.files[f.rel] ?? null) !== f.base)) {
      return fail('the skill was pinned or its recorded base changed since classification', 'abandoned');
    }
    js.status = 'applying';
    writeJournal(ctx.journal, ctx.backups);
    try {
      for (const file of js.files) {
        if (file.pre !== null) file.backup = backupFile(ctx.journal.id, file.rel, confinedSkillChildWrite(skillsRoot, file.rel, { dryRun: true }), file.pre, ctx.backups);
      }
    } catch (err) {
      return fail(`changed since classification: ${(err as Error).message}`, 'abandoned');
    }
    writeJournal(ctx.journal, ctx.backups);
    const renamed: JournalFile[] = [];
    try {
      for (const [i, file] of js.files.entries()) {
        ctx.opts.hooks?.beforeRename?.(file.rel);
        const target = confinedSkillChildWrite(skillsRoot, file.rel);
        if (hashTarget(target) !== file.pre) return fail(`${file.rel} changed since classification`, 'rolled_back', renamed);
        mkdirSync(dirname(target), { recursive: true });
        renameSync(staged[i]!, target);
        renamed.push(file);
        ctx.opts.hooks?.afterRename?.(file.rel);
      }
      const problems = ctx.validate(skillsRoot, outcome.slug);
      if (problems.length) return fail(problems.join('; '), 'rolled_back', renamed);
    } catch (err) {
      return fail((err as Error).message, 'rolled_back', renamed);
    }
    js.status = 'committed';
    writeJournal(ctx.journal, ctx.backups);
    const bases = Object.fromEntries(outcome.files.filter(f => !f.sharedDep).map(f => [f.rel, f.post]));
    try {
      await updateState(state => ({ state: withSkillBases(state, skillsRoot, { [outcome.slug]: bases }), result: null }), { statePath: ctx.opts.statePath });
    } catch (err) {
      return { ...outcome, result: 'updated', notes: [...outcome.notes, `files updated; the base record was not saved (${(err as Error).message}), so a later update treats this skill as locally edited and skips it`] };
    }
    return { ...outcome, result: 'updated' };
  } finally {
    rmSync(stage, { recursive: true, force: true });
  }
}

function summarize(skills: SkillOutcome[]): UpdateResult['summary'] {
  const summary = { updated: 0, would_update: 0, current: 0, skipped: 0, failed: 0, not_installed: 0 };
  for (const s of skills) summary[s.result]++;
  return summary;
}

/** Run the update (or, with dryRun, the preview). The caller holds the workspace writer lock for opts.skillsRoot. */
export async function runSkillpackUpdate(opts: UpdateOptions): Promise<UpdateResult> {
  const backups = opts.backups ?? backupsRoot();
  const manifest = loadBundleManifest(opts.gbrainRoot);
  const slugs = opts.slugs ?? bundledSkillSlugs(manifest);
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- root selection, not a child join: the install's own root (findGbrainOrDie) plus the constant 'skills'
  const history = loadVerifiedSkillsLockHistory(join(opts.gbrainRoot, 'skills'));
  const pending = pendingJournals({ root: backups, skillsRoot: opts.skillsRoot }).map(j => j.id);
  if (pending.length && !opts.dryRun) {
    throw new OperationError('skillpack_update_incomplete',
      `An earlier skillpack update of ${opts.skillsRoot} did not finish (backup ${pending[0]}); nothing was changed now.`,
      `Put the interrupted skills back with gbrain skillpack restore ${pending[0]} (it refuses files you changed since; name them with --skip), then run the update again.`);
  }
  const ctx: ClassifyContext = {
    gbrainRoot: opts.gbrainRoot, skillsRoot: opts.skillsRoot, manifest, history,
    records: loadState({ statePath: opts.statePath }).roots?.[opts.skillsRoot] ?? {},
    acceptHistorical: opts.acceptHistorical === true, noDiff: opts.noDiff === true,
  };
  const outcomes = slugs.map(slug => classifySkill(ctx, slug));
  const withoutShared = (o: SkillOutcome, taken: Set<string>): SkillOutcome => {
    const files = o.files.filter(f => !(f.sharedDep && f.state !== 'unchanged' && taken.has(f.rel)));
    const changes = files.filter(f => f.state !== 'unchanged').map(f => f.rel);
    return changes.length ? { ...o, files, changes } : { ...o, files, changes, result: 'current' };
  };
  const claim = (o: SkillOutcome, taken: Set<string>) => { for (const f of o.files) if (f.sharedDep && f.state !== 'unchanged') taken.add(f.rel); };
  const base = {
    dry_run: opts.dryRun === true, skills_root: opts.skillsRoot,
    history: history.ok ? { verified: true } : { verified: false, reason: history.reason },
    pending_journals: pending,
  };
  const updatable = outcomes.filter(o => o.result === 'would_update');
  if (opts.dryRun || updatable.length === 0) {
    const claimed = new Set<string>();
    const preview = outcomes.map(o => {
      if (o.result !== 'would_update') return o;
      const planned = withoutShared(o, claimed);
      claim(planned, claimed);
      return planned;
    });
    return { ...base, journal: null, summary: summarize(preview), skills: preview, restore_command: null };
  }
  removeStaleStages(opts.skillsRoot);
  const journal: Journal = {
    schema_version: 'gbrain-skillpack-journal-v1', id: newJournalId(), status: 'pending', skills_root: opts.skillsRoot,
    created_at: new Date().toISOString(), pid: process.pid,
    skills: updatable.map(o => ({
      slug: o.slug, status: 'planned',
      files: o.files.filter(f => f.state !== 'unchanged').map(f => ({ rel: f.rel, pre: f.pre, post: f.post, base_before: f.base, backup: null })),
    })),
  };
  writeJournal(journal, backups);
  const apply: ApplyContext = { opts, journal, backups, validate: opts.validate ?? defaultValidator(opts.skillsRoot) };
  const results: SkillOutcome[] = [];
  const written = new Set<string>();
  for (const outcome of outcomes) {
    const js = journal.skills.find(s => s.slug === outcome.slug);
    if (!js) {
      results.push(outcome);
      continue;
    }
    const planned = withoutShared(outcome, written);
    if (planned.result !== 'would_update') {
      journal.skills = journal.skills.filter(s => s !== js);
      writeJournal(journal, backups);
      results.push(planned);
      continue;
    }
    js.files = js.files.filter(file => planned.changes.includes(file.rel));
    const result = await applySkill(apply, planned, js);
    if (result.result === 'updated') claim(planned, written);
    results.push(result);
  }
  journal.status = 'complete';
  writeJournal(journal, backups);
  pruneJournals(backups);
  const failed = results.some(r => r.result === 'failed');
  return { ...base, journal: journal.id, summary: summarize(results), skills: results, restore_command: failed ? `gbrain skillpack restore ${journal.id}` : null };
}

export interface RestoreResult {
  id: string;
  skills_root: string;
  files: RestorePlanFile[];
}

/** Put back every applied file of journal `id` that still holds the update's bytes. The caller holds the workspace lock for the journal's root. */
export async function runSkillpackRestore(opts: { id: string; skip?: string[]; statePath?: string; backups?: string }): Promise<RestoreResult> {
  const backups = opts.backups ?? backupsRoot();
  const journal = readJournal(opts.id, backups);
  const plan = planRestore(journal, new Set(opts.skip ?? []));
  const conflicts = plan.filter(f => f.action === 'conflict').map(f => f.rel);
  if (conflicts.length) {
    throw new OperationError('skillpack_restore_conflict',
      `Refusing to restore ${opts.id}: ${conflicts.length} file(s) changed after the update: ${conflicts.join(', ')}. Nothing was restored.`,
      `Keep your later edits and restore the rest with gbrain skillpack restore ${opts.id} ${conflicts.map(c => `--skip ${c}`).join(' ')}.`);
  }
  const byRel = new Map(journal.skills.flatMap(s => s.files.map(f => [f.rel, f] as const)));
  for (const item of plan) {
    if (item.action !== 'restore' && item.action !== 'remove') continue;
    if (!undoFile(journal.id, journal.skills_root, byRel.get(item.rel)!, backups)) {
      throw new OperationError('skillpack_restore_conflict', `${item.rel} changed while it was being restored.`,
        `Run gbrain skillpack restore ${opts.id} again, adding --skip ${item.rel} to keep the newer edit.`);
    }
  }
  const putBack = new Set(plan.filter(f => f.action !== 'skipped').map(f => `${f.slug}\u0000${f.rel}`));
  await updateState(state => {
    const root = { ...(state.roots?.[journal.skills_root] ?? {}) };
    for (const skill of journal.skills) {
      const record = root[skill.slug];
      if (!record) continue;
      const files = { ...record.files };
      for (const file of skill.files) {
        if (!putBack.has(`${skill.slug}\u0000${file.rel}`)) continue;
        if (file.base_before === null) delete files[file.rel];
        else files[file.rel] = file.base_before;
      }
      root[skill.slug] = { ...record, files };
    }
    return { state: { ...state, roots: { ...state.roots, [journal.skills_root]: root } }, result: null };
  }, { statePath: opts.statePath });
  for (const skill of journal.skills) if (skill.status === 'applying' || skill.status === 'committed') skill.status = 'restored';
  journal.status = 'restored';
  writeJournal(journal, backups);
  removeStaleStages(journal.skills_root);
  pruneJournals(backups);
  return { id: journal.id, skills_root: journal.skills_root, files: plan };
}

/** Pin or unpin `slug` under `skillsRoot`. A pinned skill is never updated by --update-untouched. Returns whether anything changed. */
export async function setSkillPinned(skillsRoot: string, slug: string, pinned: boolean, opts: { statePath?: string } = {}): Promise<boolean> {
  return updateState(state => {
    const root = { ...(state.roots?.[skillsRoot] ?? {}) };
    const record = root[slug];
    if ((record?.pinned === true) === pinned) return { state: null, result: false };
    const { pinned: _old, ...rest } = record ?? { files: {}, recorded_at: new Date().toISOString() };
    if (pinned) root[slug] = { ...rest, pinned: true };
    else if (Object.keys(rest.files ?? {}).length) root[slug] = rest;
    else delete root[slug];
    return { state: { ...state, roots: { ...state.roots, [skillsRoot]: root } }, result: true };
  }, { statePath: opts.statePath });
}

/** A file a scaffold considered: written now, or already present. */
export interface ScaffoldedFile {
  source?: string;
  target: string;
  outcome: 'wrote_new' | 'skipped_existing';
  sharedDep: boolean;
  pairedSource?: boolean;
}

/**
 * Record the install's base for each skill file a scaffold wrote, or found
 * byte-identical to the bundle. Shared dependencies, paired sources and
 * pre-existing files that differ are not recorded (they are not gbrain's
 * install). Without a `source` (the harness bridge's rendered files), the
 * written bytes on disk are the base. The files are already written, so a
 * state file that cannot be read or locked is a warning on stderr, not a
 * failure: without a base, a later --update-untouched skips the skill.
 */
export async function recordScaffoldBases(skillsRoot: string, files: readonly ScaffoldedFile[], opts: { statePath?: string } = {}): Promise<void> {
  const root = skillsRootKey(skillsRoot);
  const bases: Record<string, Record<string, string>> = {};
  for (const f of files) {
    if (f.sharedDep || f.pairedSource || (!f.source && f.outcome !== 'wrote_new')) continue;
    const rel = relative(root, skillsRootKey(f.target)).split(sep).join('/');
    if (!rel || relativeEscapesRoot(rel) || !rel.includes('/')) continue;
    const current = hashTarget(f.target);
    const expected = f.source ? sha256(readFileSync(f.source)) : current;
    if (current === null || current !== expected) continue;
    (bases[rel.split('/')[0]!] ??= {})[rel] = current;
  }
  if (Object.keys(bases).length === 0) return;
  try {
    await updateState(state => ({ state: withSkillBases(state, root, bases), result: null }), opts);
  } catch (err) {
    console.error(`[skillpack] the skill files were written, but their install bases were not recorded (${(err as Error).message}); a later --update-untouched treats these skills as locally edited and skips them.`);
  }
}