Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
38.0 KB
Raw Blame
/**
 * skillpack/harness-bridge.ts — persona-curated copy of bundled skills into
 * a harness's native skills dir (cathedral-7, the Skill Bridge).
 *
 * The bridge reuses the live scaffold seam (bundle.ts enumerateScaffoldEntries
 * + copy.ts copyArtifacts) with three deltas:
 *   - slugs resolve against the skills/manifest.json universe (6 of the 8
 *     plugin-lane additions are not in openclaw.plugin.json#skills);
 *   - targets are rooted at an arbitrary destination dir (the harness skills
 *     dir), never a workspace — paired `sources:` files are skipped (a
 *     harness skills dir cannot host src/ trees);
 *   - optional cold-pull STUB mode swaps each SKILL.md body for a pointer at
 *     the gbrain MCP `get_skill` op while shipping the shared-dep closure
 *     (32 skills reference sibling convention files; a cold body without
 *     them is broken).
 *
 * Safety posture:
 *   - frontmatter fail-loud gate BEFORE any write (a frontmatterless
 *     SKILL.md bricks Codex sessions — the reason skills/install/ was
 *     deleted);
 *   - target-side confinement (assertTargetsConfined) BEFORE any write —
 *     copy.ts's rejectSymlinks/confineRealpath guard SOURCES only;
 *   - refuse-overwrite is inherited from copyArtifacts (user owns files);
 *   - written-only ownership in bridge-state (skipped_existing is never
 *     recorded; remove/rollback can only touch files the bridge created).
 *
 * Flag-registry note: this file is scanned for skillpack's flag allowlist
 * (facadeExpansion + one-level dep walk harvests bare dash-dash tokens from
 * comments AND strings) — spell foreign (non-skillpack) CLI flags WITHOUT
 * leading dashes everywhere in this file, including the stub template.
 */

import { assertLegacySkillFilesystemWrite, confinedSkillChildWrite } from './writer-guard.ts';
import {
  existsSync,
  lstatSync,
  mkdirSync,
  readFileSync,
  readdirSync,
  realpathSync,
  rmSync,
  rmdirSync,
  writeFileSync,
} from 'fs';
import { createHash } from 'crypto';
import { dirname, join, resolve, sep } from 'path';

import { enumerateScaffoldEntries, loadBundleManifest, pathSlug, BundleError } from './bundle.ts';
import { copyArtifacts, CopyError, type CopyItem, type CopyOutcome } from './copy.ts';
import { parseSkillFrontmatter } from '../skill-frontmatter.ts';
import { unifiedDiff } from './diff-text.ts';
import { parseUnifiedDiff, applyHunks } from './apply-hunks.ts';
import {
  loadBridgeState,
  saveBridgeState,
  recordBridgeWrites,
  removeBridgeSlugs,
  findBridgeEntry,
  type BridgeEntry,
  type BridgeMode,
  type BridgeWriteRecord,
} from './bridge-state.ts';

/**
 * Bridge harness vocabulary. Deliberately its own union: bootstrap.ts's
 * `Harness` is unexported and excludes openclaw; the receipt-row type in
 * bootstrap/format.ts already owns the name HarnessTarget. Follow-up (f)
 * unifies the registries.
 */
export const BRIDGE_HARNESSES = ['claude-code', 'openclaw', 'codex', 'opencode'] as const;
export type BridgeHarness = (typeof BRIDGE_HARNESSES)[number];

export function isBridgeHarness(v: string): v is BridgeHarness {
  return (BRIDGE_HARNESSES as readonly string[]).includes(v);
}

/** First line of every stub body — the mode ground truth that survives
 *  state loss in both directions (present = stub, absent = full). */
export const STUB_MARKER = '<!-- gbrain-skill-stub v1 -->';

export type BridgeErrorCode =
  | 'frontmatter_missing'
  | 'write_failed'
  | 'target_escape'
  | 'catalog_unresolvable'
  | 'invalid_args'
  | 'not_owned';

export class BridgeError extends Error {
  constructor(
    message: string,
    public code: BridgeErrorCode,
    public offendingPath?: string,
  ) {
    super(message);
    this.name = 'BridgeError';
  }
}

export function sha256Hex(content: string | Buffer): string {
  return createHash('sha256').update(content).digest('hex');
}

/**
 * Map a scaffold entry's workspace-rooted rel path (`skills/<slug>/...` or
 * `skills/conventions/...`) to the harness dest. Strips the `skills/`
 * prefix and joins under destDir — never dirname() arithmetic, so a custom
 * dest that isn't literally named "skills" still roots correctly.
 */
// Semgrep path-join suppressions in this file: the harness bridge runs on the
// LOCAL operator-invoked CLI plane only (destDir comes from the operator's
// own flags / host specs), and every computed target is checked by
// assertTargetsConfined — lexical containment plus a realpath prefix check —
// before any write or remove. The flagged joins are either inputs to that
// gate or the gate's own resolve() comparisons.
export function bridgeTargetPath(destDir: string, relWorkspaceTarget: string): string {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  return join(destDir, relWorkspaceTarget.replace(/^skills\//, ''));
}

interface EntryMeta {
  /** Target path relative to destDir (the bridge-state ledger key). */
  rel: string;
  /** Owning slug; null for shared-dep files. */
  slug: string | null;
  isSkillMd: boolean;
}

/** Shared (plan + reference) mapping from a scaffold entry to bridge metadata. */
function entryMeta(entry: { relWorkspaceTarget: string; sharedDep: boolean }): EntryMeta {
  const rel = entry.relWorkspaceTarget.replace(/^skills\//, '');
  const slug = entry.sharedDep ? null : pathSlug(join('skills', rel.split('/')[0]));
  const isSkillMd = !entry.sharedDep && /(^|[\\/])SKILL\.md$/.test(rel);
  return { rel, slug, isSkillMd };
}

export interface BridgePlanItem {
  /** Absolute source path in the gbrain tree. */
  source: string;
  /** Absolute target path under destDir. */
  target: string;
  /** Target path relative to destDir (the bridge-state ledger key). */
  relTarget: string;
  /** Owning slug; null for shared-dep files. */
  slug: string | null;
  sharedDep: boolean;
  isSkillMd: boolean;
  /** Rendered stub content (stub mode, SKILL.md items only). */
  content?: string;
}

export interface BridgePlan {
  destDir: string;
  mode: BridgeMode;
  slugs: string[];
  items: BridgePlanItem[];
  /** Paired `sources:` files skipped (a harness dir has no src/ tree). */
  pairedSourcesSkipped: number;
  /** Slugs whose EXISTING SKILL.md is in the other mode (file marker is
   *  ground truth). Their items are DROPPED from the plan — apply never
   *  half-converts an install; remedy = remove + re-run. */
  modeConflicts: string[];
}

export interface PlanHarnessBridgeOptions {
  gbrainRoot: string;
  destDir: string;
  slugs: readonly string[];
  mode: BridgeMode;
}

/**
 * Enumerate + gate. Throws BridgeError('frontmatter_missing') naming every
 * offending SKILL.md BEFORE anything would be written; reports (does not
 * throw on) mode conflicts so the caller can decide.
 */
export function planHarnessBridge(opts: PlanHarnessBridgeOptions): BridgePlan {
  if (opts.slugs.length === 0) {
    throw new BridgeError('no skills selected (empty persona resolution?)', 'invalid_args');
  }
  const manifest = loadBundleManifest(opts.gbrainRoot);
  const entries = enumerateScaffoldEntries({
    gbrainRoot: opts.gbrainRoot,
    skillSlugs: opts.slugs,
    universe: 'manifest',
    manifest,
  });

  const items: BridgePlanItem[] = [];
  let pairedSourcesSkipped = 0;
  const frontmatterViolations: string[] = [];
  const modeConflictSlugs = new Set<string>();

  for (const entry of entries) {
    if (entry.pairedSource) {
      pairedSourcesSkipped++;
      continue;
    }
    const { rel, slug, isSkillMd } = entryMeta(entry);

    // Stub mode ships shared deps AND aux files: skill bodies reference
    // both (../conventions/… and sibling files like a MANIFEST-PATTERN.md),
    // and the cold-pulled body still needs them on disk — get_skill serves
    // only the SKILL.md body itself.

    const target = bridgeTargetPath(opts.destDir, entry.relWorkspaceTarget);
    const item: BridgePlanItem = {
      source: entry.source,
      target,
      relTarget: rel,
      slug,
      sharedDep: entry.sharedDep,
      isSkillMd,
    };

    if (isSkillMd) {
      const sourceContent = readFileSync(entry.source, 'utf-8');
      const fm = parseSkillFrontmatter(sourceContent);
      if (!fm || !fm.name) {
        // A frontmatterless SKILL.md makes Codex error at session start —
        // fail loud before ANY write rather than brick the harness.
        frontmatterViolations.push(entry.source);
      } else if (opts.mode === 'stub') {
        item.content = renderSkillStub(sourceContent, slug ?? fm.name);
      }
      // Mode conflict: judge the EXISTING file, not state (survives state
      // loss in both directions — marker present = stub, absent = full).
      if (existsSync(target) && slug) {
        const existing = readTargetFile(target);
        const fileMode: BridgeMode = existing.includes(STUB_MARKER) ? 'stub' : 'full';
        if (fileMode !== opts.mode) modeConflictSlugs.add(slug);
      }
    }
    items.push(item);
  }

  if (frontmatterViolations.length > 0) {
    throw new BridgeError(
      `refusing to install: SKILL.md missing parseable frontmatter with a name (would brick harness discovery): ${frontmatterViolations.join(', ')}`,
      'frontmatter_missing',
    );
  }

  // Mode-conflicted slugs are DROPPED wholesale: applying their non-conflicted
  // items would half-convert the install (e.g. a full-mode run over a stub
  // would land aux files next to a stub SKILL.md and flip the ledger mode
  // while the marker still says stub). Report-only, never partially applied.
  const conflicted = new Set(modeConflictSlugs);
  const applicableItems = conflicted.size > 0 ? items.filter(i => i.slug === null || !conflicted.has(i.slug)) : items;

  return {
    destDir: opts.destDir,
    mode: opts.mode,
    slugs: [...opts.slugs],
    items: applicableItems,
    pairedSourcesSkipped,
    modeConflicts: [...conflicted].sort(),
  };
}

/** Read an existing target defensively: a symlink at the target is install-dir
 *  tampering (the bridge only ever writes regular files) and unreadable
 *  targets (EISDIR, EACCES) surface as typed errors, not raw stacks. */
function readTargetFile(target: string): string {
  try {
    if (lstatSync(target).isSymbolicLink()) {
      throw new BridgeError(
        `${target}: the installed file is a symlink — refusing to read through it (the bridge only writes regular files; remove it and re-run)`,
        'target_escape',
        target,
      );
    }
    return readFileSync(target, 'utf-8');
  } catch (err) {
    if (err instanceof BridgeError) throw err;
    throw new BridgeError(
      `cannot read ${target}: ${(err as Error).message}`,
      'write_failed',
      target,
    );
  }
}

/**
 * Render a cold-pull stub for one skill. The source SKILL.md's frontmatter
 * block is preserved VERBATIM (name / description / triggers are the warm
 * discovery contract); the body becomes a pointer at the gbrain MCP
 * `get_skill` op. The fallback text is honest about reachability: on stdio
 * servers a per-client surface cannot be persisted, and `request_tools`
 * never widens past the operator's ceiling.
 */
export function renderSkillStub(sourceContent: string, slug: string): string {
  const fmMatch = sourceContent.replace(/\r\n/g, '\n').match(/^---\n[\s\S]*?\n---/);
  if (!fmMatch) {
    throw new BridgeError(
      `cannot render stub for '${slug}': SKILL.md has no frontmatter block`,
      'frontmatter_missing',
    );
  }
  const body =
    `${STUB_MARKER}\n\n` +
    `This is a cold-pull stub installed by \`gbrain skillpack scaffold\`. The full\n` +
    `skill body is served by your gbrain brain, so it is always current.\n\n` +
    `To use this skill: call the gbrain MCP tool \`get_skill\` with\n` +
    `\`{"name": "${slug}"}\`, read the returned instructions, and follow them\n` +
    `exactly.\n\n` +
    `If \`get_skill\` is not in your tool list, the gbrain MCP server's surface is\n` +
    `too narrow for skill serving — ask the operator to run \`gbrain serve\` with\n` +
    `surface \`full\` (HTTP clients may try the \`request_tools\` tool; stdio\n` +
    `servers cannot persist a wider surface, and no client can exceed the\n` +
    `operator's ceiling). Local CLI fallback that always works:\n` +
    `\`gbrain skill ${slug}\`.\n`;
  return `${fmMatch[0]}\n\n${body}`;
}

/**
 * Target-side confinement [CEO-F3/CX5]: every planned target must resolve
 * inside destDir, judged on the REAL filesystem — the deepest existing
 * ancestor of each target is realpath'd and prefix-checked against the
 * realpath of destDir, so both `..` traversal and symlinked-parent escapes
 * are rejected BEFORE any write. A target that exists as a SYMLINK itself
 * (including a dangling one — invisible to existsSync, followed by
 * writeFileSync) is rejected too. copy.ts's own confinement gates guard
 * sources only; this is the mirror for targets.
 *
 * When destDir does not exist yet, only the lexical check can run here —
 * applyHarnessBridge therefore CREATES destDir before calling this, so the
 * realpath branch always executes on the apply path.
 */
export function assertTargetsConfined(destDir: string, targets: readonly string[]): void {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  const logicalRoot = resolve(destDir);
  const rootExists = existsSync(logicalRoot);
  const realRoot = rootExists ? realpathSync(logicalRoot) : null;
  for (const t of targets) {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    const logical = resolve(t);
    if (logical !== logicalRoot && !logical.startsWith(logicalRoot + sep)) {
      throw new BridgeError(`${t}: escapes the install destination (${destDir})`, 'target_escape', t);
    }
    // A symlink AT the target (dangling links pass existsSync=false but
    // writeFileSync would write THROUGH them) is refused outright.
    try {
      if (lstatSync(logical).isSymbolicLink()) {
        throw new BridgeError(
          `${t}: the target is a symlink — refusing to write through it`,
          'target_escape',
          t,
        );
      }
    } catch (err) {
      if (err instanceof BridgeError) throw err;
      // ENOENT: no filesystem object at the target — the normal case.
    }
    if (realRoot === null) continue; // lexical-only until the root exists
    // Deepest existing ancestor, realpath'd: catches a symlinked parent dir
    // pointing outside the dest.
    let probe = dirname(logical);
    while (!existsSync(probe)) {
      const up = dirname(probe);
      if (up === probe) break;
      probe = up;
    }
    let realProbe: string;
    try {
      realProbe = realpathSync(probe);
    } catch {
      continue;
    }
    if (realProbe !== realRoot && !realProbe.startsWith(realRoot + sep)) {
      throw new BridgeError(
        `${t}: an existing parent directory resolves outside the install destination (${realProbe})`,
        'target_escape',
        t,
      );
    }
  }
}

export interface ApplyHarnessBridgeOptions {
  harness: string;
  scope?: 'user' | 'project';
  persona: string | null;
  gbrainVersion: string;
  dryRun?: boolean;
  statePath?: string;
  nowIso: string;
}

export interface BridgeFileResult {
  target: string;
  relTarget: string;
  slug: string | null;
  sharedDep: boolean;
  outcome: 'wrote_new' | 'skipped_existing';
}

export interface BridgeApplyResult {
  dryRun: boolean;
  destDir: string;
  mode: BridgeMode;
  files: BridgeFileResult[];
  summary: {
    wroteNew: number;
    skippedExisting: number;
    pairedSourcesSkipped: number;
    modeConflicts: string[];
  };
}

/** Ledger pseudo-slug for shared-dep files (conventions/, _*.md). They belong
 *  to every slug at once, so ownership hashes live under a reserved key —
 *  remove skips it (shared files outlive any one slug), the reference lens
 *  reads it so shared-dep drift classifies three-way like everything else. */
export const SHARED_DEP_LEDGER_KEY = '_shared';

/** #5912: the skill slugs an install's ledger owns, sorted, without the reserved shared-dep key. */
export function ownedBridgeSlugs(entry: Pick<BridgeEntry, 'written'> | null | undefined): string[] {
  return entry ? Object.keys(entry.written).filter(s => s !== SHARED_DEP_LEDGER_KEY).sort() : [];
}

/** Record wrote_new hashes into bridge-state (used by both the success path
 *  and the mid-run-failure partial path — an fs error must not orphan the
 *  files that DID land). */
function recordLedger(
  results: readonly { target: string; outcome: CopyOutcome; sha256?: string }[],
  planItems: readonly BridgePlanItem[],
  plan: BridgePlan,
  opts: ApplyHarnessBridgeOptions,
): void {
  const perSlug = new Map<string, Record<string, string>>();
  for (let i = 0; i < results.length; i++) {
    const r = results[i];
    if (r.outcome !== 'wrote_new' || !r.sha256) continue;
    const key = planItems[i].slug ?? SHARED_DEP_LEDGER_KEY;
    const bySlug = perSlug.get(key) ?? {};
    bySlug[planItems[i].relTarget] = r.sha256;
    perSlug.set(key, bySlug);
  }
  if (perSlug.size === 0) return;
  const writes: BridgeWriteRecord[] = [...perSlug.entries()].map(([slug, fileMap]) => ({
    slug,
    mode: plan.mode,
    files: fileMap,
  }));
  const state = loadBridgeState({ statePath: opts.statePath });
  const next = recordBridgeWrites(
    state,
    {
      harness: opts.harness,
      dest: plan.destDir,
      scope: opts.scope,
      persona: opts.persona,
      mode: plan.mode,
      gbrainVersion: opts.gbrainVersion,
      nowIso: opts.nowIso,
    },
    writes,
  );
  saveBridgeState(next, { statePath: opts.statePath });
}

/**
 * Execute a plan: confinement gate → copy (refuse-overwrite) → bridge-state
 * upsert with install-time sha256 per written file. All fs failures wrap as
 * typed BridgeError('write_failed') with the offending path; a mid-run
 * failure still records ownership of everything that landed before it.
 */
export function applyHarnessBridge(plan: BridgePlan, opts: ApplyHarnessBridgeOptions): BridgeApplyResult {
  const dryRun = opts.dryRun ?? false;
  if (!dryRun) {
    assertLegacySkillFilesystemWrite(plan.destDir);
    for (const item of plan.items) assertLegacySkillFilesystemWrite(item.target);
    if (opts.statePath) assertLegacySkillFilesystemWrite(opts.statePath);
  }
  // Create destDir BEFORE the confinement gate so the realpath branch always
  // runs on the apply path (a not-yet-existing dest would otherwise get the
  // lexical check only — a symlinked ancestor could slip past it).
  if (!dryRun) {
    try {
      mkdirSync(plan.destDir, { recursive: true });
    } catch (err) {
      throw new BridgeError(
        `cannot create the install destination ${plan.destDir}: ${(err as Error).message}`,
        'write_failed',
        plan.destDir,
      );
    }
  }
  assertTargetsConfined(plan.destDir, plan.items.map(i => i.target));

  const copyItems: CopyItem[] = plan.items.map(i => ({
    source: i.source,
    target: i.target,
    ...(i.content != null ? { content: i.content } : {}),
  }));

  let copyResult;
  try {
    copyResult = copyArtifacts(copyItems, { dryRun, computeSha256: true });
  } catch (err) {
    if (err instanceof CopyError) {
      // Mid-run write failure: bank ownership of files 1..k−1 before
      // surfacing the error, so remove/reference still know about them.
      if (err.code === 'write_failed' && err.partial && !dryRun) {
        try {
          recordLedger(err.partial, plan.items, plan, opts);
        } catch {
          // Ledger write also failing must not mask the original error.
        }
      }
      throw err;
    }
    throw new BridgeError(
      `write failed under ${plan.destDir}: ${(err as Error).message}`,
      'write_failed',
      plan.destDir,
    );
  }

  // copyArtifacts returns one result per item, in order — the ledger below
  // zips by index, so a drift here would mis-attribute ownership hashes.
  if (copyResult.files.length !== plan.items.length) {
    throw new BridgeError(
      `copy result count (${copyResult.files.length}) diverged from the plan (${plan.items.length}) — refusing to record ownership`,
      'write_failed',
      plan.destDir,
    );
  }

  const files: BridgeFileResult[] = copyResult.files.map((f, i) => ({
    target: f.target,
    relTarget: plan.items[i].relTarget,
    slug: plan.items[i].slug,
    sharedDep: plan.items[i].sharedDep,
    outcome: f.outcome,
  }));

  // Written-only ownership: hash exactly what landed (computed by the copy
  // from the same buffer it wrote — no second read, no rehash window).
  if (!dryRun) recordLedger(copyResult.files, plan.items, plan, opts);

  return {
    dryRun,
    destDir: plan.destDir,
    mode: plan.mode,
    files,
    summary: {
      wroteNew: files.filter(f => f.outcome === 'wrote_new').length,
      skippedExisting: files.filter(f => f.outcome === 'skipped_existing').length,
      pairedSourcesSkipped: plan.pairedSourcesSkipped,
      modeConflicts: plan.modeConflicts,
    },
  };
}

/**
 * Stub-preflight leg [CX2]: verify every requested slug is servable from
 * the skills dir the MCP server would resolve. Returns the missing slugs
 * (empty = all servable). The publish-gate and surface checks live in the
 * CLI layer (core must not import src/mcp).
 */
export function verifySlugsServable(skillsDir: string, slugs: readonly string[]): string[] {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  return slugs.filter(slug => !existsSync(join(skillsDir, slug, 'SKILL.md')));
}

export type HarnessRefStatus = 'identical' | 'differs' | 'missing';
export type HarnessRefDiffersKind = 'local_edit' | 'upstream_drift' | 'unknown';

export interface HarnessRefFile {
  target: string;
  relTarget: string;
  slug: string | null;
  sharedDep: boolean;
  status: HarnessRefStatus;
  /** Mode the comparison judged this file in (existing-file marker wins). */
  mode: BridgeMode;
  /** Present when status='differs' and the install-time hash is known. */
  differsKind?: HarnessRefDiffersKind;
  unifiedDiff?: string;
}

export interface HarnessRefResult {
  destDir: string;
  files: HarnessRefFile[];
  summary: { identical: number; differs: number; missing: number };
}

export interface HarnessReferenceOptions {
  gbrainRoot: string;
  destDir: string;
  slugs: readonly string[];
  harness: string;
  statePath?: string;
  /** Skip unified-diff rendering (summary counts only) — the status
   *  command's lens consumes counts and would discard every diff string
   *  (the O(N*M) LCS is the dominant cost on drifted files). Default true. */
  includeDiffs?: boolean;
}

/**
 * The harness diff lens. Expected content per file is mode-aware: an
 * existing SKILL.md whose body carries the stub marker is compared against
 * the RENDERED stub (a fresh stub reads identical); everything else is
 * compared against current source bytes. With the install-time hash from
 * bridge-state, `differs` splits three-way [OV3]: the file still matching
 * what we wrote = upstream_drift; anything else = local_edit.
 */
export function runHarnessReference(opts: HarnessReferenceOptions): HarnessRefResult {
  const manifest = loadBundleManifest(opts.gbrainRoot);
  const entries = enumerateScaffoldEntries({
    gbrainRoot: opts.gbrainRoot,
    skillSlugs: opts.slugs,
    universe: 'manifest',
    manifest,
  });
  const state = loadBridgeState({ statePath: opts.statePath });
  const stateEntry = findBridgeEntry(state, { harness: opts.harness, dest: opts.destDir });

  const includeDiffs = opts.includeDiffs ?? true;
  // Per-slug mode ground truth for expected-absence decisions: the state
  // record when present, else the installed SKILL.md's marker (the same
  // file-marker fallback the per-file comparison uses — survives state
  // loss in both directions [CX8]).
  const slugMode = (slug: string): BridgeMode => {
    const recorded = stateEntry?.written[slug]?.mode;
    if (recorded) return recorded;
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    const skillMd = join(opts.destDir, slug, 'SKILL.md');
    try {
      if (existsSync(skillMd) && readFileSync(skillMd, 'utf-8').includes(STUB_MARKER)) return 'stub';
    } catch {}
    return 'full';
  };

  const files: HarnessRefFile[] = [];
  for (const entry of entries) {
    if (entry.pairedSource) continue;
    const { rel, slug, isSkillMd } = entryMeta(entry);
    const target = bridgeTargetPath(opts.destDir, entry.relWorkspaceTarget);
    const stateMode: BridgeMode = slug ? slugMode(slug) : 'full';

    if (!existsSync(target)) {
      files.push({ target, relTarget: rel, slug, sharedDep: entry.sharedDep, status: 'missing', mode: stateMode });
      continue;
    }

    const actual = readTargetFile(target);
    const sourceContent = readFileSync(entry.source, 'utf-8');
    const fileMode: BridgeMode = isSkillMd && actual.includes(STUB_MARKER) ? 'stub' : 'full';
    const expected = fileMode === 'stub' && isSkillMd && slug ? renderSkillStub(sourceContent, slug) : sourceContent;

    if (actual === expected) {
      files.push({ target, relTarget: rel, slug, sharedDep: entry.sharedDep, status: 'identical', mode: fileMode });
      continue;
    }
    const installedHash = stateEntry?.written[slug ?? SHARED_DEP_LEDGER_KEY]?.files[rel];
    const differsKind: HarnessRefDiffersKind = installedHash
      ? sha256Hex(actual) === installedHash
        ? 'upstream_drift'
        : 'local_edit'
      : 'unknown';
    files.push({
      target,
      relTarget: rel,
      slug,
      sharedDep: entry.sharedDep,
      status: 'differs',
      mode: fileMode,
      differsKind,
      ...(includeDiffs
        ? { unifiedDiff: unifiedDiff(actual, expected, { oldPath: `local/${rel}`, newPath: `gbrain/${rel}` }) }
        : {}),
    });
  }

  return {
    destDir: opts.destDir,
    files,
    summary: {
      identical: files.filter(f => f.status === 'identical').length,
      differs: files.filter(f => f.status === 'differs').length,
      missing: files.filter(f => f.status === 'missing').length,
    },
  };
}

export interface HarnessRefApplyFile {
  target: string;
  relTarget: string;
  status:
    | 'applied'
    | 'partial'
    | 'refused_stub'
    | 'refused_local_edit'
    | 'refused_unknown'
    | 'identical'
    | 'missing';
  hunksApplied: number;
  hunksConflicted: number;
  conflicts: string[];
}

export interface HarnessRefApplyResult {
  dryRun: boolean;
  files: HarnessRefApplyFile[];
  summary: {
    totalHunksApplied: number;
    totalHunksConflicted: number;
    refusedStub: number;
    refusedLocalEdit: number;
    refusedUnknown: number;
  };
}

/**
 * `--apply-clean-hunks` for a harness install [CX10]. Applies ONLY to files
 * with PROVEN upstream drift (install-time hash matches the current file):
 *   - stub-marked files are refused (stubs are regenerated: remove the skill,
 *     then re-run the scaffold — a plain re-run refuses to overwrite);
 *   - LOCAL-EDIT files are refused — the lens's own guidance prints
 *     "local_edit → your change; keep it";
 *   - UNKNOWN-provenance files are refused — shared files never written by
 *     this bridge, pre-existing files the install skipped, or state-loss:
 *     the diff is computed from the live file, so every hunk would "apply
 *     cleanly" and rewrite content the bridge never owned.
 * After a fully-clean apply the ledger hash is refreshed to the new content,
 * so the NEXT upstream change still classifies as drift, not local_edit.
 */
export function runHarnessReferenceApply(
  opts: HarnessReferenceOptions & { dryRun?: boolean },
): HarnessRefApplyResult {
  const dryRun = opts.dryRun ?? false;
  const ref = runHarnessReference(opts);
  const files: HarnessRefApplyFile[] = [];
  let totalApplied = 0;
  let totalConflicted = 0;
  let refusedStub = 0;
  let refusedLocalEdit = 0;
  let refusedUnknown = 0;
  const ledgerRefresh: Array<{ slugKey: string; relTarget: string; sha256: string; mode: BridgeMode }> = [];

  // Same real-filesystem write gate as the install path — an installed file
  // (or parent) later swapped for a symlink must not redirect the write.
  const writeTargets = ref.files.filter(f => f.status === 'differs').map(f => f.target);
  if (writeTargets.length > 0) assertTargetsConfined(opts.destDir, writeTargets);
  if (!dryRun) {
    for (const target of writeTargets) assertLegacySkillFilesystemWrite(target);
    if (opts.statePath) assertLegacySkillFilesystemWrite(opts.statePath);
  }

  for (const f of ref.files) {
    if (f.status === 'identical' || f.status === 'missing') {
      files.push({
        target: f.target,
        relTarget: f.relTarget,
        status: f.status,
        hunksApplied: 0,
        hunksConflicted: 0,
        conflicts: [],
      });
      continue;
    }
    if (f.mode === 'stub') {
      refusedStub++;
      files.push({
        target: f.target,
        relTarget: f.relTarget,
        status: 'refused_stub',
        hunksApplied: 0,
        hunksConflicted: 0,
        conflicts: [
          'stub-mode file: stubs are never merged — remove the skill (gbrain skillpack remove with the harness and skill flags), then re-run the scaffold to regenerate it',
        ],
      });
      continue;
    }
    if (f.differsKind === 'local_edit') {
      refusedLocalEdit++;
      files.push({
        target: f.target,
        relTarget: f.relTarget,
        status: 'refused_local_edit',
        hunksApplied: 0,
        hunksConflicted: 0,
        conflicts: ['local edit (file no longer matches the install-time hash): your change wins — patch by hand if you want the upstream version'],
      });
      continue;
    }
    if (f.differsKind !== 'upstream_drift') {
      // 'unknown' — no install-time hash: a shared file predating the hash
      // ledger, a pre-existing file the install skipped (never ours), or a
      // lost state file. Rewriting would violate written-only ownership.
      refusedUnknown++;
      files.push({
        target: f.target,
        relTarget: f.relTarget,
        status: 'refused_unknown',
        hunksApplied: 0,
        hunksConflicted: 0,
        conflicts: [
          'unknown provenance (no install-time hash in the ledger): the bridge cannot prove this file is its own unedited write — patch by hand, or remove and re-scaffold the skill',
        ],
      });
      continue;
    }
    const actual = readTargetFile(f.target);
    const diffText = f.unifiedDiff ?? '';
    const parsed = parseUnifiedDiff(diffText);
    const res = applyHunks(actual, parsed);
    if (!dryRun && res.applied > 0) {
      assertLegacySkillFilesystemWrite(f.target);
      try {
        writeFileSync(f.target, res.text);
      } catch (err) {
        throw new BridgeError(
          `write failed for ${f.target}: ${(err as Error).message}`,
          'write_failed',
          f.target,
        );
      }
      if (res.conflicted === 0) {
        ledgerRefresh.push({
          slugKey: f.slug ?? SHARED_DEP_LEDGER_KEY,
          relTarget: f.relTarget,
          sha256: sha256Hex(res.text),
          mode: f.mode,
        });
      }
    }
    totalApplied += res.applied;
    totalConflicted += res.conflicted;
    files.push({
      target: f.target,
      relTarget: f.relTarget,
      status: res.conflicted > 0 ? 'partial' : 'applied',
      hunksApplied: res.applied,
      hunksConflicted: res.conflicted,
      conflicts: res.outcomes.filter(o => o.status !== 'applied').map(o => `hunk ${o.hunk}: ${o.status}`),
    });
  }

  // Refresh the ledger for fully-clean applies — without this, the applied
  // file no longer matches the install-time hash and the NEXT upstream
  // change would misclassify as local_edit forever.
  if (!dryRun && ledgerRefresh.length > 0) {
    const state = loadBridgeState({ statePath: opts.statePath });
    const entry = findBridgeEntry(state, { harness: opts.harness, dest: opts.destDir });
    if (entry) {
      const perSlug = new Map<string, Record<string, string>>();
      for (const r of ledgerRefresh) {
        const bySlug = perSlug.get(r.slugKey) ?? {};
        bySlug[r.relTarget] = r.sha256;
        perSlug.set(r.slugKey, bySlug);
      }
      const writes: BridgeWriteRecord[] = [...perSlug.entries()].map(([slug, fileMap]) => ({
        slug,
        mode: entry.written[slug]?.mode ?? 'full',
        files: fileMap,
      }));
      const next = recordBridgeWrites(
        state,
        {
          harness: opts.harness,
          dest: opts.destDir,
          scope: entry.scope,
          persona: entry.last_persona,
          mode: entry.last_mode,
          gbrainVersion: entry.gbrain_version,
          nowIso: new Date().toISOString(),
        },
        writes,
      );
      saveBridgeState(next, { statePath: opts.statePath });
    }
  }

  return {
    dryRun,
    files,
    summary: {
      totalHunksApplied: totalApplied,
      totalHunksConflicted: totalConflicted,
      refusedStub,
      refusedLocalEdit,
      refusedUnknown,
    },
  };
}

export interface BridgeRemoveResult {
  dryRun: boolean;
  removedFiles: string[];
  /** Ledger-owned files the user has since edited — kept, not deleted
   *  ("never your own files" includes files that became yours). */
  keptEdited: string[];
  prunedDirs: string[];
  /** Slugs requested but not owned by the bridge (nothing to remove). */
  notOwned: string[];
}

/**
 * Remove state-owned files for the given slugs (or every owned slug when
 * slugs is null) [OV4]. NEVER touches files outside the written ledger —
 * pre-existing user files were never recorded, and skipped_existing was
 * never ours. Empty slug dirs are pruned afterwards.
 */
export function removeHarnessBridge(opts: {
  harness: string;
  destDir: string;
  slugs: readonly string[] | null;
  dryRun?: boolean;
  statePath?: string;
  nowIso: string;
}): BridgeRemoveResult {
  const dryRun = opts.dryRun ?? false;
  if (!dryRun) {
    assertLegacySkillFilesystemWrite(opts.destDir);
    if (opts.statePath) assertLegacySkillFilesystemWrite(opts.statePath);
  }
  const state = loadBridgeState({ statePath: opts.statePath });
  const entry = findBridgeEntry(state, { harness: opts.harness, dest: opts.destDir });
  // The shared-dep ledger key never enumerates as a removable slug: shared
  // files belong to every installed skill at once, so removing one slug (or
  // even all of them) leaves the conventions in place.
  const owned = ownedBridgeSlugs(entry);
  const requested = opts.slugs === null ? owned : [...opts.slugs].filter(s => s !== SHARED_DEP_LEDGER_KEY);
  const notOwned = requested.filter(s => !owned.includes(s));
  const toRemove = requested.filter(s => owned.includes(s));
  if (!dryRun) for (const slug of toRemove) for (const rel of Object.keys(entry!.written[slug].files)) {
    try { confinedSkillChildWrite(opts.destDir, rel); } catch (error) {
      if ((error as { code?: string }).code === 'target_escape') throw new BridgeError((error as Error).message, 'target_escape', rel);
      throw error;
    }
  }

  const removedFiles: string[] = [];
  const keptEdited: string[] = [];
  const prunedDirs = new Set<string>();
  // Confinement on the way out too — the ledger is machine-owned but a
  // hand-edited relpath must not escape the dest. Same real-filesystem
  // discipline as the install gate: lexical containment AND a realpath
  // prefix check on the deepest existing ancestor (a symlinked component
  // recorded into the ledger must not redirect the delete outside dest).
  assertTargetsConfined(
    opts.destDir,
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    toRemove.flatMap(slug => Object.keys(entry!.written[slug].files).map(rel => join(opts.destDir, rel))),
  );
  for (const slug of toRemove) {
    const rec = entry!.written[slug];
    for (const [rel, installedHash] of Object.entries(rec.files)) {
      // Same rel set assertTargetsConfined just vetted above.
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      const abs = join(opts.destDir, rel);
      if (!existsSync(abs)) continue;
      // "Never your own files" includes files that BECAME yours: a
      // bridge-written file the user has since edited no longer matches its
      // install-time hash — keep it (it leaves the ledger either way and is
      // henceforth user-owned).
      try {
        if (sha256Hex(readFileSync(abs)) !== installedHash) {
          keptEdited.push(abs);
          continue;
        }
      } catch {
        keptEdited.push(abs);
        continue;
      }
      if (!dryRun) {
        assertLegacySkillFilesystemWrite(abs);
        try {
          rmSync(abs);
        } catch (err) {
          throw new BridgeError(
            `remove failed for ${abs}: ${(err as Error).message}`,
            'write_failed',
            abs,
          );
        }
      }
      removedFiles.push(abs);
      prunedDirs.add(dirname(abs));
    }
  }

  // Prune emptied dirs (bottom-up, then walk each pruned dir's parents up to
  // dest — removing a slug's only child dir can empty the slug dir itself).
  const pruned: string[] = [];
  if (!dryRun) {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    const destReal = resolve(opts.destDir);
    const candidates = [...prunedDirs].sort((a, b) => b.length - a.length);
    for (let dir of candidates) {
      while (dir !== destReal && dir.startsWith(destReal + sep)) {
        assertLegacySkillFilesystemWrite(dir);
        try {
          if (!existsSync(dir) || readdirSync(dir).length > 0) break;
          rmdirSync(dir);
          pruned.push(dir);
        } catch {
          break; // best-effort prune
        }
        dir = dirname(dir);
      }
    }
  }

  if (!dryRun && toRemove.length > 0) {
    const next = removeBridgeSlugs(
      state,
      { harness: opts.harness, dest: opts.destDir, nowIso: opts.nowIso },
      toRemove,
    );
    saveBridgeState(next, { statePath: opts.statePath });
  }

  return { dryRun, removedFiles, keptEdited, prunedDirs: pruned, notOwned };
}

/** Guard against a caller passing a symlink AS the dest dir itself. */
export function assertDestNotSymlink(destDir: string): void {
  if (!existsSync(destDir)) return;
  const stat = lstatSync(destDir);
  if (stat.isSymbolicLink()) {
    throw new BridgeError(
      `${destDir}: the install destination is a symlink — refusing (pass the resolved directory)`,
      'target_escape',
      destDir,
    );
  }
}

/** Re-exported for the CLI's confinement error taxonomy. */
export { BundleError };