@smeltjs/core 0.3.0 → 0.4.0

package/dist/cli/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"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","sourcesContent":["import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\n\nimport { CliUsageError } from '../errors.ts';\nimport { nodeCommand, portablePath, shimScriptPath, smeltBinPath } from '../harness/paths.ts';\nimport { hasShim, TIER_HONESTY } from '../harness/profile.ts';\nimport type {\n  HarnessInstallContext,\n  HarnessJsonHooks,\n  HarnessProfile,\n} from '../harness/profile.ts';\nimport {\n  GUARD_EVENTS,\n  GUARD_ONLY_FILES,\n  HARNESSES,\n  harnessById,\n  JSON_HOOK_FILES,\n  LIFECYCLE_EVENTS,\n  MANAGED_EVENTS,\n} from '../harness/registry.ts';\nimport {\n  instructionSnippet,\n  OURS_TOKEN,\n  SNIPPET_END_MD,\n  SNIPPET_START_MD,\n} from '../harness/snippet.ts';\nimport { DEFAULT_SUGGESTION_BUDGET_BYTES, DEFAULT_THRESHOLD_BYTES } from '../hooks/guard-core.ts';\nimport type { EnforcementMode } from '../hooks/guard-core.ts';\n\nimport { answerReader, CLI_NAME } from './shell.ts';\nimport type { AnswerStream } from './shell.ts';\nimport {\n  CONFIG_FILE_NAME,\n  CONFIG_VERSION,\n  findConfigFile,\n  parseConfig,\n  renderConfig,\n} from './config.ts';\nimport type { SmeltConfig, SmeltConfigHooks } from './config.ts';\n\n/**\n * `smelt hooks install` / `smelt hooks remove` — the multi-harness guard preset.\n *\n * The design: one zero-dependency guard core\n * (`src/hooks/guard-core.ts`), thin per-harness shims mapping each harness's native\n * hook schema onto it, and this installer, which writes the harness config that wires\n * a shim in — plus an instruction-file snippet as belt and braces, because the\n * snippet is also what teaches the model to run `smelt retrieve` after a deny.\n *\n * Every per-harness fact lives in that harness's {@link HarnessProfile}\n * (`src/harness/<id>.ts`), including what to write and how to take it back out. This\n * module owns only what is the *same* for every harness: the byte-faithful JSON merge,\n * the marker-block upsert, the wizard, and the two plans below — folds over\n * `profile.install`, with no case list of its own.\n *\n * Harnesses come in three honesty tiers (docs/research/2026-09-02-harness-capability-matrix.md):\n *\n *  - **verified** — Claude Code, Codex: schemas verified against primary docs and\n *    exercised against recorded fixtures; first-class targets.\n *  - **experimental** — Gemini, Grok, Hermes, Cursor, opencode, Cline: hook schemas\n *    mapped from the capability matrix but not yet smoke-tested green against the\n *    real binary. Labelled as such in code, docs, and this installer's output.\n *  - **advisory** — KiloCode, Aider: no usable hook API, so what ships is\n *    instructions (and, for KiloCode, a permissions/MCP sketch). Nothing enforces\n *    them, and the output says so rather than implying a guard exists.\n *\n * The wizard discipline is `smelt init`'s, verbatim: every step accepts `back`,\n * nothing is written until a final confirm that lists every file, and an existing\n * file is never overwritten without an explicit per-file `yes` — guarded by\n * `test/guards/hooks-preset.test.ts`, with mutation `hooks-install-overwrite-without-consent`\n * proving the guard goes red.\n */\n\n/** Where the wizard's bytes come from and go. Injected so `runHooks` tests in-process. */\nexport interface HooksIo {\n  /**\n   * Scripted answers in, one line at a time. Structural on purpose; see\n   * {@link AnswerStream}.\n   */\n  readonly input: AnswerStream;\n  readonly output: (text: string) => void;\n  /** Project directory: detection, config discovery, and every write are relative to it. */\n  readonly cwd: string;\n  /** Home directory for detection only. Tests point it at a temp dir; nothing writes here. */\n  readonly home?: string;\n}\n\nexport { instructionSnippet, SNIPPET_END_MD, SNIPPET_START_MD };\n\n/** A harness whose config directory exists in the project or the home directory. */\nexport function detectedHarnesses(cwd: string, home: string): readonly HarnessProfile[] {\n  return HARNESSES.filter(\n    (profile) =>\n      profile.detect.some((path) => existsSync(join(cwd, path))) ||\n      profile.detectHome.some((path) => existsSync(join(home, path))),\n  );\n}\n\n/* ------------------------------------------------------------------------------------\n * Generated content\n * ---------------------------------------------------------------------------------- */\n\n/** Claude-style hook entry: one command under an optional matcher. */\nfunction commandEntry(matcher: string | undefined, command: string): unknown {\n  return {\n    ...(matcher === undefined ? {} : { matcher }),\n    hooks: [{ type: 'command', command }],\n  };\n}\n\n/**\n * The hook command a harness's entries run: its own shim script, through node.\n *\n * @throws {Error} when a profile declares a JSON hook file but ships no shim — a\n *   registry bug, pinned by `test/guards/harness-registry.test.ts`, not a user error.\n */\nfunction shimCommand(profile: HarnessProfile, cwd: string): string {\n  /* v8 ignore next 5 -- unreachable: pinned by the harness-registry guard */\n  if (!hasShim(profile)) {\n    throw new Error(\n      `smelt: harness \"${profile.id}\" wires a hook command but ships no shim script.`,\n    );\n  }\n  return nodeCommand(cwd, shimScriptPath(profile));\n}\n\n/**\n * One harness's hook entries: the guard under each matcher its schema spells, plus\n * the two session-lifecycle hooks for the harnesses whose schema carries them. Every\n * toggle the wizard offers is a key that is present or absent here — an absent key is\n * how a re-run turns a toggle *off*, because the merge deletes what it no longer sees.\n */\nfunction jsonHookEvents(\n  step: HarnessJsonHooks,\n  ctx: HarnessInstallContext,\n  command: string,\n): Record<string, readonly unknown[]> {\n  // The trailing shell comment tags the entry as this installer's (see isOursEntry):\n  // a bare `cli/bin.js` substring would also match some other npm CLI's built binary.\n  const stats = `${nodeCommand(ctx.cwd, smeltBinPath(), 'stats')} 2>/dev/null || true # ${OURS_TOKEN}`;\n  const map = `${nodeCommand(\n    ctx.cwd,\n    smeltBinPath(),\n    `map . --budget ${String(ctx.budgetBytes)} --cache .smelt/tags`,\n  )} 2>/dev/null || true # ${OURS_TOKEN}`;\n\n  return {\n    ...(ctx.guard\n      ? {\n          [step.event]: step.matchers.map((matcher) =>\n            step.entry === 'bare-command' ? { command } : commandEntry(matcher, command),\n          ),\n        }\n      : {}),\n    ...(step.lifecycle && ctx.statsOnStop\n      ? { [LIFECYCLE_EVENTS.stats]: [commandEntry(undefined, stats)] }\n      : {}),\n    ...(step.lifecycle && ctx.mapOnStart\n      ? { [LIFECYCLE_EVENTS.map]: [commandEntry('startup|resume|clear|compact', map)] }\n      : {}),\n  };\n}\n\n/**\n * True for a hook entry this installer wrote. Matched on the shim script paths and the\n * `smelt:hooks` token the stats/map commands carry — never on a substring as generic\n * as `cli/bin.js`, which another npm CLI's built binary could share: remove and\n * re-install may only ever touch entries that are provably smelt's.\n */\nfunction isOursEntry(entry: unknown): boolean {\n  const text = JSON.stringify(entry) ?? '';\n  return text.includes('hooks/shims/') || text.includes(OURS_TOKEN);\n}\n\n/**\n * Merge our hook entries into a JSON settings file, preserving everything foreign\n * **byte-faithfully**: the merged `hooks` value is spliced into the original text, so\n * unknown top-level keys, string escapes, number spellings, indentation and key order\n * outside the `hooks` property ride through verbatim (an installer\n * that reformats somebody's settings file has edited what it was never asked to).\n * Inside `hooks`, unmanaged events and other people's entries under managed events\n * are preserved; our previous entries are replaced (that is what makes a re-run edit\n * toggles), and events left with no entries disappear. A semantic no-op returns the\n * input text unchanged. Returns `undefined` when the existing file is not a JSON\n * object — the caller skips the file rather than clobbering something it cannot\n * understand.\n */\nexport function mergeJsonHooks(\n  existingText: string | undefined,\n  events: Record<string, readonly unknown[]>,\n  shape: { readonly version?: number } = {},\n): string | undefined {\n  let root: Record<string, unknown> = {};\n  if (existingText !== undefined) {\n    try {\n      const parsed: unknown = JSON.parse(existingText);\n      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;\n      root = parsed as Record<string, unknown>;\n    } catch {\n      return undefined;\n    }\n  }\n  const hooksValue = root['hooks'];\n  const existingHooks =\n    typeof hooksValue === 'object' && hooksValue !== null && !Array.isArray(hooksValue)\n      ? (hooksValue as Record<string, unknown>)\n      : undefined;\n  const hooks = { ...existingHooks };\n\n  for (const event of MANAGED_EVENTS) {\n    const existing = Array.isArray(hooks[event]) ? (hooks[event] as unknown[]) : [];\n    const foreign = existing.filter((entry) => !isOursEntry(entry));\n    const ours = events[event] ?? [];\n    const merged = [...foreign, ...ours];\n    if (merged.length > 0) hooks[event] = merged;\n    else delete hooks[event];\n  }\n\n  const mergedHooks = Object.keys(hooks).length > 0 ? hooks : undefined;\n\n  // A brand-new file: nothing to preserve, render fresh two-space JSON.\n  if (existingText === undefined) {\n    const fresh: Record<string, unknown> = {};\n    if (mergedHooks !== undefined) fresh['hooks'] = mergedHooks;\n    if (shape.version !== undefined) fresh['version'] = shape.version;\n    return `${JSON.stringify(fresh, null, 2)}\\n`;\n  }\n\n  const hooksChanged =\n    JSON.stringify(existingHooks ?? null) !== JSON.stringify(mergedHooks ?? null);\n  const needsVersion = shape.version !== undefined && root['version'] === undefined;\n  if (!hooksChanged && !needsVersion) return existingText;\n\n  const newline = existingText.includes('\\r\\n') ? '\\r\\n' : '\\n';\n  const indent = /\\n([ \\t]+)\"/.exec(existingText)?.[1] ?? '  ';\n  let text = existingText;\n\n  if (hooksChanged) {\n    const scan = scanJsonTopLevel(text);\n    /* v8 ignore next -- unreachable: JSON.parse accepted the same text above */\n    if (scan === undefined) return undefined;\n    const property = scan.properties.find((candidate) => candidate.key === 'hooks');\n    if (mergedHooks === undefined) {\n      if (property !== undefined) text = removeJsonProperty(text, scan, property);\n    } else {\n      const rendered = renderJsonValue(mergedHooks, indent, newline);\n      text =\n        property !== undefined\n          ? `${text.slice(0, property.valueStart)}${rendered}${text.slice(property.valueEnd)}`\n          : insertJsonProperty(text, scan, 'hooks', rendered, indent, newline);\n    }\n  }\n  if (needsVersion) {\n    const scan = scanJsonTopLevel(text);\n    /* v8 ignore next -- unreachable: every splice above keeps the text valid JSON */\n    if (scan === undefined) return undefined;\n    text = insertJsonProperty(\n      text,\n      scan,\n      'version',\n      JSON.stringify(shape.version),\n      indent,\n      newline,\n    );\n  }\n  return text;\n}\n\n/** One top-level property of a JSON object, located by offsets in its source text. */\ninterface JsonTopLevelProperty {\n  readonly key: string;\n  /** Offset of the key's opening quote. */\n  readonly keyStart: number;\n  /** Offset of the value's first byte. */\n  readonly valueStart: number;\n  /** Offset one past the value's last byte. */\n  readonly valueEnd: number;\n}\n\ninterface JsonTopLevelScan {\n  /** Offset of the root object's `{`. */\n  readonly open: number;\n  /** Offset of the root object's `}`. */\n  readonly close: number;\n  readonly properties: readonly JsonTopLevelProperty[];\n}\n\n/**\n * Locate the top-level properties of a JSON object *in its source text*, so one\n * property can be replaced, inserted or removed while every other byte of the file\n * rides through verbatim. `undefined` when the text is not an object — callers have\n * already `JSON.parse`d it, so that is belt and braces, not a validator.\n */\nfunction scanJsonTopLevel(text: string): JsonTopLevelScan | undefined {\n  let i = skipJsonWhitespace(text, 0);\n  if (text[i] !== '{') return undefined;\n  const open = i;\n  i = skipJsonWhitespace(text, i + 1);\n  const properties: JsonTopLevelProperty[] = [];\n  if (text[i] === '}') return { open, close: i, properties };\n  for (;;) {\n    if (text[i] !== '\"') return undefined;\n    const keyStart = i;\n    const keyEnd = skipJsonString(text, i);\n    if (keyEnd === undefined) return undefined;\n    const key = JSON.parse(text.slice(keyStart, keyEnd)) as string;\n    i = skipJsonWhitespace(text, keyEnd);\n    if (text[i] !== ':') return undefined;\n    const valueStart = skipJsonWhitespace(text, i + 1);\n    const valueEnd = skipJsonValue(text, valueStart);\n    if (valueEnd === undefined) return undefined;\n    properties.push({ key, keyStart, valueStart, valueEnd });\n    i = skipJsonWhitespace(text, valueEnd);\n    if (text[i] === ',') {\n      i = skipJsonWhitespace(text, i + 1);\n      continue;\n    }\n    if (text[i] === '}') return { open, close: i, properties };\n    return undefined;\n  }\n}\n\nfunction skipJsonWhitespace(text: string, from: number): number {\n  let i = from;\n  while (i < text.length && ' \\t\\r\\n'.includes(text[i]!)) i += 1;\n  return i;\n}\n\n/** `from` points at `\"`; returns the offset one past the closing quote. */\nfunction skipJsonString(text: string, from: number): number | undefined {\n  let i = from + 1;\n  while (i < text.length) {\n    if (text[i] === '\\\\') i += 2;\n    else if (text[i] === '\"') return i + 1;\n    else i += 1;\n  }\n  return undefined;\n}\n\nfunction skipJsonValue(text: string, from: number): number | undefined {\n  const first = text[from];\n  if (first === '\"') return skipJsonString(text, from);\n  if (first === '{' || first === '[') {\n    let depth = 0;\n    let i = from;\n    while (i < text.length) {\n      const ch = text[i]!;\n      if (ch === '\"') {\n        const end = skipJsonString(text, i);\n        if (end === undefined) return undefined;\n        i = end;\n        continue;\n      }\n      if (ch === '{' || ch === '[') depth += 1;\n      else if (ch === '}' || ch === ']') {\n        depth -= 1;\n        if (depth === 0) return i + 1;\n      }\n      i += 1;\n    }\n    return undefined;\n  }\n  // number / true / false / null\n  let i = from;\n  while (i < text.length && !',}] \\t\\r\\n'.includes(text[i]!)) i += 1;\n  return i > from ? i : undefined;\n}\n\n/** A JSON value indented for embedding at a top-level property position. */\nfunction renderJsonValue(value: unknown, indent: string, newline: string): string {\n  return JSON.stringify(value, null, indent).split('\\n').join(`${newline}${indent}`);\n}\n\nfunction removeJsonProperty(\n  text: string,\n  scan: JsonTopLevelScan,\n  property: JsonTopLevelProperty,\n): string {\n  const index = scan.properties.indexOf(property);\n  const next = scan.properties[index + 1];\n  if (next !== undefined) {\n    // Delete through the separating comma and whitespace, up to the next key.\n    return text.slice(0, property.keyStart) + text.slice(next.keyStart);\n  }\n  const previous = scan.properties[index - 1];\n  // Last (or only) property: delete the preceding comma (if any) with it.\n  const from = previous !== undefined ? previous.valueEnd : scan.open + 1;\n  return text.slice(0, from) + text.slice(property.valueEnd);\n}\n\nfunction insertJsonProperty(\n  text: string,\n  scan: JsonTopLevelScan,\n  key: string,\n  renderedValue: string,\n  indent: string,\n  newline: string,\n): string {\n  const entry = `${JSON.stringify(key)}: ${renderedValue}`;\n  if (scan.properties.length === 0) {\n    return `${text.slice(0, scan.open + 1)}${newline}${indent}${entry}${newline}${text.slice(scan.close)}`;\n  }\n  const last = scan.properties[scan.properties.length - 1]!;\n  return `${text.slice(0, last.valueEnd)},${newline}${indent}${entry}${text.slice(last.valueEnd)}`;\n}\n\n/** Replace this installer's marker block in `existingText`, or append it. */\nexport function upsertMarkerBlock(\n  existingText: string | undefined,\n  block: string,\n  start: string,\n  end: string,\n): string {\n  if (existingText === undefined || existingText.trim() === '') return block;\n  const startIndex = existingText.indexOf(start);\n  const endIndex = existingText.indexOf(end);\n  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {\n    const before = existingText.slice(0, startIndex);\n    const after = existingText.slice(endIndex + end.length).replace(/^\\n/, '');\n    return `${before}${block}${after}`;\n  }\n  return `${existingText.replace(/\\n*$/, '\\n\\n')}${block}`;\n}\n\n/** Remove the marker block. `undefined` when nothing (or only whitespace) remains. */\nexport function stripMarkerBlock(\n  existingText: string,\n  start: string,\n  end: string,\n): string | undefined {\n  const startIndex = existingText.indexOf(start);\n  const endIndex = existingText.indexOf(end);\n  if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) return existingText;\n  const stripped =\n    existingText.slice(0, startIndex).replace(/\\n+$/, '\\n') +\n    existingText.slice(endIndex + end.length).replace(/^\\n+/, '');\n  return stripped.trim() === '' ? undefined : stripped;\n}\n\n/* ------------------------------------------------------------------------------------\n * Planning\n * ---------------------------------------------------------------------------------- */\n\ninterface PlannedFile {\n  /** Display path, relative to the project. */\n  readonly name: string;\n  readonly path: string;\n  readonly content: string;\n  readonly exists: boolean;\n  readonly unchanged: boolean;\n  /** chmod after writing (the cline hook must be executable). */\n  readonly mode?: number;\n}\n\ninterface SkippedFile {\n  readonly name: string;\n  readonly why: string;\n}\n\ninterface PlannedRemoval {\n  readonly name: string;\n  readonly path: string;\n  /** `'delete'` removes the file; `'modify'` writes `content` (ours stripped out). */\n  readonly action: 'delete' | 'modify';\n  readonly content?: string;\n}\n\nexport interface HooksChoices {\n  harnesses: HarnessProfile[];\n  guard: boolean;\n  statsOnStop: boolean;\n  mapOnStart: boolean;\n  enforcement: EnforcementMode;\n  thresholdBytes: number;\n}\n\ninterface InstallPlan {\n  readonly files: readonly PlannedFile[];\n  readonly skipped: readonly SkippedFile[];\n  readonly notes: readonly string[];\n}\n\nfunction planFile(cwd: string, name: string, content: string, mode?: number): PlannedFile {\n  const path = join(cwd, name);\n  const exists = existsSync(path);\n  const unchanged = exists && readFileSync(path, 'utf8') === content;\n  return { name, path, content, exists, unchanged, ...(mode === undefined ? {} : { mode }) };\n}\n\nfunction readIfExists(path: string): string | undefined {\n  return existsSync(path) ? readFileSync(path, 'utf8') : undefined;\n}\n\n/**\n * Every file `install` would write, computed against the current disk state — pure\n * planning, nothing written. A fold over each chosen profile's `install` list and its\n * instruction layer; all per-harness knowledge is in the profiles. Shared instruction\n * files (several harnesses read AGENTS.md) are planned once.\n *\n * @throws {CliUsageError} when an existing `smelt.config.json` is malformed — the\n *   same refusal every other subcommand makes; an installer that guessed around a\n *   broken config would write settings the guard then ignores.\n */\nexport function planInstall(cwd: string, choices: HooksChoices): InstallPlan {\n  const files = new Map<string, PlannedFile>();\n  const skipped: SkippedFile[] = [];\n  const notes: string[] = [];\n\n  // -- smelt.config.json: the guard's runtime settings live here, not in any harness\n  // file, so every shim reads one source of truth.\n  const configPath = findConfigFile(cwd) ?? join(cwd, CONFIG_FILE_NAME);\n  const existingConfig =\n    readIfExists(configPath) === undefined\n      ? undefined\n      : parseConfig(readFileSync(configPath, 'utf8'), configPath);\n  const hooksBlock: SmeltConfigHooks = {\n    thresholdBytes: choices.thresholdBytes,\n    enforcement: choices.enforcement,\n  };\n  const budgetBytes = existingConfig?.defaultBudgetBytes ?? DEFAULT_SUGGESTION_BUDGET_BYTES;\n  files.set(configPath, {\n    name: portablePath(cwd, configPath),\n    path: configPath,\n    content: renderConfigWithHooks(existingConfig, hooksBlock),\n    exists: existsSync(configPath),\n    unchanged: readIfExists(configPath) === renderConfigWithHooks(existingConfig, hooksBlock),\n  });\n\n  const ctx: HarnessInstallContext = {\n    cwd,\n    guard: choices.guard,\n    statsOnStop: choices.statsOnStop,\n    mapOnStart: choices.mapOnStart,\n    thresholdBytes: choices.thresholdBytes,\n    budgetBytes,\n  };\n  const snippet = instructionSnippet(choices.thresholdBytes, budgetBytes);\n\n  const planJsonHooks = (\n    name: string,\n    events: Record<string, readonly unknown[]>,\n    shape: { readonly version?: number } = {},\n  ): void => {\n    const path = join(cwd, name);\n    // Nothing to install and nothing to strip: don't create an empty hooks file.\n    if (Object.keys(events).length === 0 && !existsSync(path)) return;\n    const merged = mergeJsonHooks(readIfExists(path), events, shape);\n    if (merged === undefined) {\n      skipped.push({\n        name,\n        why: 'exists but is not a JSON object — fix or remove it, then re-run',\n      });\n      return;\n    }\n    files.set(path, planFile(cwd, name, merged));\n  };\n\n  const planBlockFile = (\n    name: string,\n    block: string,\n    start: string,\n    end: string,\n    skipWhen?: { readonly contains: string; readonly why: string },\n  ): void => {\n    const path = join(cwd, name);\n    if (files.has(path)) return; // a shared file (AGENTS.md), already planned\n    const existing = readIfExists(path);\n    // A file that already carries its owner's version of what this block does is\n    // theirs to edit, not ours: say so, and touch nothing.\n    if (\n      skipWhen !== undefined &&\n      existing !== undefined &&\n      !existing.includes(start) &&\n      existing.includes(skipWhen.contains)\n    ) {\n      skipped.push({ name, why: skipWhen.why });\n      return;\n    }\n    files.set(path, planFile(cwd, name, upsertMarkerBlock(existing, block, start, end)));\n  };\n\n  for (const profile of choices.harnesses) {\n    for (const step of profile.install) {\n      switch (step.kind) {\n        case 'json-hooks':\n          planJsonHooks(\n            step.file,\n            jsonHookEvents(step, ctx, shimCommand(profile, cwd)),\n            step.shape ?? {},\n          );\n          break;\n        case 'marker-block':\n          planBlockFile(step.file, step.block(ctx), step.start, step.end, step.skipWhen);\n          break;\n        case 'own-file':\n          if (step.guardOnly && !ctx.guard) break;\n          files.set(join(cwd, step.file), planFile(cwd, step.file, step.content(ctx), step.mode));\n          break;\n      }\n    }\n\n    if (profile.instructions === 'snippet') {\n      planBlockFile(profile.instructionFile, snippet, SNIPPET_START_MD, SNIPPET_END_MD);\n    } else {\n      files.set(\n        join(cwd, profile.instructionFile),\n        planFile(cwd, profile.instructionFile, profile.instructions(ctx)),\n      );\n    }\n\n    for (const caveat of profile.caveats) notes.push(`${profile.name}: ${caveat}`);\n  }\n\n  return { files: [...files.values()], skipped, notes };\n}\n\n/** Where the installed config points the persistent store, relative to the config file. */\nexport const DEFAULT_STORE_DIR = '.smelt/store';\n\n/**\n * Existing config re-rendered with the hooks block, other fields carried verbatim —\n * except that a config with **no** store block gains a directory store. The deny\n * reasons and the instruction snippet teach `smelt retrieve <hash>`, and retrieval\n * across processes needs a persistent store (`smelt retrieve` refuses a memory\n * store, exit 2) — an install whose own guard promises a command the installed\n * config cannot run would be the exact silent-failure shape this project refuses.\n * An *explicit* `{\"kind\":\"memory\"}` is respected; the guard then conditions its\n * retrieve promise on the store kind instead (`retrieveSentence` in guard-core).\n *\n * That store injection is this verb's **policy**, which is why it lives here; the\n * bytes are written by `renderConfig` in `config.ts`, the one writer, so a key added\n * to the schema reaches this file and `init`'s together or not at all.\n */\nexport function renderConfigWithHooks(\n  existing: SmeltConfig | undefined,\n  hooks: SmeltConfigHooks,\n): string {\n  return renderConfig({\n    smeltConfig: CONFIG_VERSION,\n    ...(existing?.defaultBudgetBytes === undefined\n      ? {}\n      : { defaultBudgetBytes: existing.defaultBudgetBytes }),\n    ...(existing?.strategy === undefined ? {} : { strategy: existing.strategy }),\n    store: existing?.store ?? { kind: 'directory', path: DEFAULT_STORE_DIR },\n    hooks,\n  });\n}\n\n/**\n * Everything `remove` would delete or strip, computed against the current disk state.\n * The mirror image of {@link planInstall}, over the same data: each install step's\n * kind is also how it comes back out — a JSON hook file is strip-merged, a marker\n * block is stripped, a file that is entirely ours is deleted.\n */\nexport function planRemove(\n  cwd: string,\n  harnesses: readonly HarnessProfile[],\n): readonly PlannedRemoval[] {\n  const removals = new Map<string, PlannedRemoval>();\n\n  const planJsonStrip = (name: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined) return;\n    const stripped = mergeJsonHooks(existing, {});\n    if (stripped === undefined || stripped === existing) return;\n    const remains: unknown = JSON.parse(stripped);\n    const empty =\n      typeof remains === 'object' &&\n      remains !== null &&\n      Object.keys(remains as Record<string, unknown>).filter((key) => key !== 'version').length ===\n        0;\n    removals.set(\n      path,\n      empty && existing.includes('hooks')\n        ? { name, path, action: 'delete' }\n        : { name, path, action: 'modify', content: stripped },\n    );\n  };\n\n  const planBlockStrip = (name: string, start: string, end: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined || !existing.includes(start)) return;\n    const stripped = stripMarkerBlock(existing, start, end);\n    removals.set(\n      path,\n      stripped === undefined\n        ? { name, path, action: 'delete' }\n        : { name, path, action: 'modify', content: stripped },\n    );\n  };\n\n  const planWholeFileDelete = (name: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined || !existing.includes(OURS_TOKEN)) return;\n    removals.set(path, { name, path, action: 'delete' });\n  };\n\n  for (const profile of harnesses) {\n    for (const step of profile.install) {\n      switch (step.kind) {\n        case 'json-hooks':\n          planJsonStrip(step.file);\n          break;\n        case 'marker-block':\n          planBlockStrip(step.file, step.start, step.end);\n          break;\n        case 'own-file':\n          planWholeFileDelete(step.file);\n          break;\n      }\n    }\n    if (profile.instructions === 'snippet') {\n      planBlockStrip(profile.instructionFile, SNIPPET_START_MD, SNIPPET_END_MD);\n    } else {\n      planWholeFileDelete(profile.instructionFile);\n    }\n  }\n\n  return [...removals.values()];\n}\n\n/* ------------------------------------------------------------------------------------\n * The wizard\n * ---------------------------------------------------------------------------------- */\n\ntype Asker = (prompt: string) => Promise<string>;\n\n/**\n * `smelt hooks <install|remove>`, start to finish. The same testability pattern as\n * `runInit`: a pure function over an input/output pair, exit code returned.\n */\nexport async function runHooks(\n  action: 'install' | 'remove',\n  harnessFlag: string | undefined,\n  io: HooksIo,\n): Promise<number> {\n  // Same adapter, same reason, as `runInit` — see the note on `answerReader`.\n  const lines = answerReader(io.input);\n  const ask = async (prompt: string): Promise<string> => {\n    io.output(prompt);\n    const next = await lines.next();\n    if (next === undefined) {\n      throw new CliUsageError(\n        `${CLI_NAME} hooks: input ended before the wizard finished. ` +\n          `Files already confirmed and written stay; nothing further was written.`,\n      );\n    }\n    return next.trim();\n  };\n\n  try {\n    return action === 'install'\n      ? await installFlow(io, ask, harnessFlag)\n      : await removeFlow(io, ask, harnessFlag);\n  } finally {\n    await lines.release();\n  }\n}\n\nfunction resolveHarnessFlag(flag: string): HarnessProfile {\n  const profile = harnessById(flag);\n  if (profile === undefined) {\n    throw new CliUsageError(\n      `${CLI_NAME} hooks: unknown harness \"${flag}\". ` +\n        `Known: ${HARNESSES.map((h) => h.id).join(', ')}.`,\n    );\n  }\n  return profile;\n}\n\nfunction tierLabel(profile: HarnessProfile): string {\n  return `${profile.id.padEnd(12)} ${profile.name.padEnd(14)} [${profile.tier}] — ${TIER_HONESTY[profile.tier]}`;\n}\n\nasync function installFlow(\n  io: HooksIo,\n  ask: Asker,\n  harnessFlag: string | undefined,\n): Promise<number> {\n  const home = io.home ?? homedir();\n  const detected = detectedHarnesses(io.cwd, home);\n\n  io.output(\n    `${CLI_NAME} hooks install — wires the smelt guard into agent-harness hooks.\\n` +\n      `Answer \\`back\\` at any step to return to the previous one. Nothing is written ` +\n      `until you confirm at the end.\\n\\n`,\n  );\n\n  const choices: HooksChoices = {\n    harnesses: harnessFlag !== undefined ? [resolveHarnessFlag(harnessFlag)] : [...detected],\n    ...presetToggles(io.cwd),\n    enforcement: 'deny',\n    thresholdBytes: DEFAULT_THRESHOLD_BYTES,\n  };\n\n  // With --harness the selection step is skipped, so the tier label — and its one\n  // line of honesty about what the tier means — is printed here instead.\n  if (harnessFlag !== undefined) {\n    for (const profile of choices.harnesses) io.output(`  ${tierLabel(profile)}\\n`);\n  }\n\n  const steps: readonly ((io_: HooksIo, ask_: Asker) => Promise<'ok' | 'back'>)[] = [\n    async (io_, ask_) =>\n      harnessFlag !== undefined ? 'ok' : stepHarnesses(io_, ask_, choices, detected),\n    async (io_, ask_) =>\n      stepToggle(io_, ask_, 'PreToolUse size-guard', guardCopy(), choices.guard, (on) => {\n        choices.guard = on;\n      }),\n    async (io_, ask_) =>\n      stepToggle(\n        io_,\n        ask_,\n        'stats on Stop',\n        `\\`smelt stats\\` runs when a session ends — the honest signal (expansion rate) ` +\n          `surfaced where the turn ends. Observation only; never blocks. Wired for ` +\n          `verified-tier harnesses (Claude Code, Codex).`,\n        choices.statsOnStop,\n        (on) => {\n          choices.statsOnStop = on;\n        },\n      ),\n    async (io_, ask_) =>\n      stepToggle(\n        io_,\n        ask_,\n        'repo map on SessionStart',\n        `\\`smelt map . --budget …\\` runs at session start and its output opens the ` +\n          `context — the agent starts oriented. Costs one map build per session. ` +\n          `Wired for verified-tier harnesses (Claude Code, Codex).`,\n        choices.mapOnStart,\n        (on) => {\n          choices.mapOnStart = on;\n        },\n      ),\n    async (io_, ask_) => stepEnforcement(io_, ask_, choices),\n    async (io_, ask_) => stepThreshold(io_, ask_, choices),\n  ];\n\n  let index = 0;\n  for (;;) {\n    while (index < steps.length) {\n      const outcome = await steps[index]!(io, ask);\n      if (outcome === 'back') {\n        if (index === 0) io.output(`This is the first step — there is nothing before it.\\n`);\n        else index -= 1;\n      } else {\n        index += 1;\n      }\n    }\n    if (choices.harnesses.length === 0) {\n      io.output(`No harness selected. Nothing to do; nothing was written.\\n`);\n      return 0;\n    }\n    const verdict = await confirmAndInstall(io, ask, choices);\n    if (verdict !== 'back') return 0;\n    index = steps.length - 1;\n  }\n}\n\nfunction guardCopy(): string {\n  return (\n    `Denies raw Reads (and simple \\`cat\\`s) of files over the size threshold, with a ` +\n    `reason naming the exact \\`smelt\\` replacement — the model still sees everything: ` +\n    `smelted first, \\`smelt retrieve\\` for the rest. Windowed reads (offset/limit) ` +\n    `always pass.`\n  );\n}\n\nasync function stepHarnesses(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n  detected: readonly HarnessProfile[],\n): Promise<'ok' | 'back'> {\n  io.output(`\\nHarnesses — detected by their config directories (project or home):\\n`);\n  for (const profile of HARNESSES) {\n    const mark = detected.includes(profile) ? '*' : ' ';\n    io.output(`  ${mark} ${tierLabel(profile)}\\n`);\n  }\n  io.output(`(* = detected here)\\n`);\n  for (;;) {\n    const current = choices.harnesses.map((profile) => profile.id).join(',') || '(none)';\n    const answer = await ask(\n      `install for which? (comma-separated ids, Enter = ${current}, or back)\\n> `,\n    );\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    const ids = answer\n      .split(',')\n      .map((id) => id.trim())\n      .filter((id) => id !== '');\n    const chosen: HarnessProfile[] = [];\n    let bad: string | undefined;\n    for (const id of ids) {\n      const profile = harnessById(id);\n      if (profile === undefined) bad = id;\n      else if (!chosen.includes(profile)) chosen.push(profile);\n    }\n    if (bad !== undefined) {\n      io.output(`Unknown harness \"${bad}\". Known: ${HARNESSES.map((h) => h.id).join(', ')}.\\n`);\n      continue;\n    }\n    choices.harnesses = chosen;\n    return 'ok';\n  }\n}\n\nasync function stepToggle(\n  io: HooksIo,\n  ask: Asker,\n  name: string,\n  copy: string,\n  current: boolean,\n  set: (on: boolean) => void,\n): Promise<'ok' | 'back'> {\n  io.output(`\\n${name} — ${copy}\\n`);\n  for (;;) {\n    const answer = await ask(`${name}? (on/off) [${current ? 'on' : 'off'}] (or back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    if (answer === 'on' || answer === 'off') {\n      set(answer === 'on');\n      return 'ok';\n    }\n    io.output(`on, off, or back.\\n`);\n  }\n}\n\nasync function stepEnforcement(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'ok' | 'back'> {\n  io.output(\n    `\\nEnforcement — what happens when the guard catches an oversized raw read:\\n` +\n      `  1. deny     — refuse with a reason naming the exact replacement command. The\\n` +\n      `                transcript stays truthful; the model runs the replacement itself.\\n` +\n      `  2. rewrite  — on harnesses whose hooks can modify tool input, substitute the\\n` +\n      `                replacement in-flight (grep/cat piped through smelt). Never\\n` +\n      `                silent: the substitution is announced in the decision reason\\n` +\n      `                where the harness has one, on stderr where it does not.\\n` +\n      `                Harnesses that cannot rewrite fall back to deny.\\n`,\n  );\n  for (;;) {\n    const current = choices.enforcement === 'deny' ? '1' : '2';\n    const answer = await ask(`enforcement (1/2) [${current}] (or back)> `);\n    if (answer === 'back') return 'back';\n    const pick = answer === '' ? current : answer;\n    if (pick === '1' || pick === '2') {\n      choices.enforcement = pick === '1' ? 'deny' : 'rewrite';\n      return 'ok';\n    }\n    io.output(`1 for deny, 2 for rewrite, or back.\\n`);\n  }\n}\n\nasync function stepThreshold(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'ok' | 'back'> {\n  io.output(\n    `\\nSize threshold — reads at or under this many bytes always pass. The ${String(\n      DEFAULT_THRESHOLD_BYTES,\n    )}-byte default comes from the measured validation in ` +\n      `docs/research/2026-09-02-agent-enforcement.md § 5.\\n`,\n  );\n  for (;;) {\n    const answer = await ask(`threshold in bytes [${String(choices.thresholdBytes)}] (or back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    if (/^\\d+$/.test(answer) && Number(answer) > 0) {\n      choices.thresholdBytes = Number(answer);\n      return 'ok';\n    }\n    io.output(`A whole number of bytes greater than zero, e.g. 8192.\\n`);\n  }\n}\n\n/**\n * A re-run reads the toggles back off what is actually installed — every JSON hook\n * file this installer writes, plus the guard-only shim files, both derived from the\n * registry — so it edits instead of resetting. Harnesses that only wire the guard\n * (gemini, grok, cursor, hermes, opencode, cline) persist no stats/map entries, so\n * after a re-run scoped to them those toggles read back as off; the defaults below\n * apply only when nothing of smelt's is installed at all.\n */\nfunction presetToggles(cwd: string): Pick<HooksChoices, 'guard' | 'statsOnStop' | 'mapOnStart'> {\n  const defaults = { guard: true, statsOnStop: true, mapOnStart: false };\n  let anyOurs = false;\n  let guard = false;\n  let statsOnStop = false;\n  let mapOnStart = false;\n\n  for (const name of JSON_HOOK_FILES) {\n    const text = readIfExists(join(cwd, name));\n    if (text === undefined) continue;\n    let hooks: Record<string, unknown> | undefined;\n    try {\n      const parsed: unknown = JSON.parse(text);\n      const hooksValue =\n        typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)\n          ? (parsed as Record<string, unknown>)['hooks']\n          : undefined;\n      hooks =\n        typeof hooksValue === 'object' && hooksValue !== null && !Array.isArray(hooksValue)\n          ? (hooksValue as Record<string, unknown>)\n          : undefined;\n    } catch {\n      hooks = undefined;\n    }\n    if (hooks === undefined) continue;\n    const installed = hooks;\n    const hasOurs = (event: string): boolean =>\n      Array.isArray(installed[event]) &&\n      (installed[event] as unknown[]).some((entry) => isOursEntry(entry));\n    if (!MANAGED_EVENTS.some((event) => hasOurs(event))) continue;\n    anyOurs = true;\n    guard ||= GUARD_EVENTS.some((event) => hasOurs(event));\n    statsOnStop ||= hasOurs('Stop');\n    mapOnStart ||= hasOurs('SessionStart');\n  }\n\n  for (const name of GUARD_ONLY_FILES) {\n    const text = readIfExists(join(cwd, name));\n    if (text !== undefined && text.includes(OURS_TOKEN)) {\n      anyOurs = true;\n      guard = true;\n    }\n  }\n\n  return anyOurs ? { guard, statsOnStop, mapOnStart } : defaults;\n}\n\nconst fileLabel = (file: PlannedFile): string => {\n  if (file.unchanged) return 'unchanged — nothing to write';\n  return file.exists ? 'exists — will ask before overwriting' : 'new';\n};\n\nasync function confirmAndInstall(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'done' | 'back'> {\n  const plan = planInstall(io.cwd, choices);\n\n  io.output(\n    `\\nAbout to write, into ${io.cwd}:\\n` +\n      plan.files.map((file) => `  ${file.name.padEnd(32)} (${fileLabel(file)})\\n`).join('') +\n      plan.skipped.map((skip) => `  ${skip.name.padEnd(32)} (SKIPPED: ${skip.why})\\n`).join('') +\n      `Nothing has been written yet.\\n`,\n  );\n\n  for (;;) {\n    const answer = await ask(`confirm (yes / no / back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === 'no') {\n      io.output(`Nothing was written.\\n`);\n      return 'done';\n    }\n    if (answer === 'yes') break;\n    io.output(`yes to write, no to leave everything untouched, back to change a setting.\\n`);\n  }\n\n  for (const file of plan.files) {\n    if (file.unchanged) {\n      io.output(`  ${file.name} — unchanged, not rewritten\\n`);\n      continue;\n    }\n    if (file.exists) {\n      // The one hard rule, same as `smelt init`: an existing file is never touched\n      // without an explicit per-file yes — not `y`, not Enter, a literal `yes`.\n      const answer = await ask(`  ${file.name} exists — overwrite it? (yes/no)> `);\n      if (answer !== 'yes') {\n        io.output(`  skipped ${file.name} — the existing file was not touched\\n`);\n        continue;\n      }\n    }\n    mkdirSync(dirname(file.path), { recursive: true });\n    writeFileSync(file.path, file.content);\n    if (file.mode !== undefined) chmodSync(file.path, file.mode);\n    io.output(`  wrote ${file.name}\\n`);\n  }\n\n  for (const note of plan.notes) io.output(`note: ${note}\\n`);\n  io.output(\n    `Done. Re-run \\`${CLI_NAME} hooks install\\` to edit toggles; ` +\n      `\\`${CLI_NAME} hooks remove\\` takes it all back out.\\n`,\n  );\n  return 'done';\n}\n\nasync function removeFlow(\n  io: HooksIo,\n  ask: Asker,\n  harnessFlag: string | undefined,\n): Promise<number> {\n  const harnesses = harnessFlag !== undefined ? [resolveHarnessFlag(harnessFlag)] : [...HARNESSES];\n  const removals = planRemove(io.cwd, harnesses);\n\n  if (removals.length === 0) {\n    io.output(`${CLI_NAME} hooks remove: nothing of smelt's found to remove in ${io.cwd}.\\n`);\n    return 0;\n  }\n\n  io.output(\n    `${CLI_NAME} hooks remove — takes smelt's hook wiring back out.\\n\\nPlanned:\\n` +\n      removals\n        .map(\n          (removal) =>\n            `  ${removal.name.padEnd(32)} (${\n              removal.action === 'delete' ? 'delete' : 'remove smelt entries, keep the rest'\n            })\\n`,\n        )\n        .join('') +\n      `${CONFIG_FILE_NAME} is left untouched — its hooks block is your config now; ` +\n      `edit or remove it there.\\nNothing has been changed yet.\\n`,\n  );\n\n  for (;;) {\n    const answer = await ask(`confirm (yes / no)> `);\n    if (answer === 'no') {\n      io.output(`Nothing was changed.\\n`);\n      return 0;\n    }\n    if (answer === 'yes') break;\n    io.output(`yes to proceed, no to leave everything untouched.\\n`);\n  }\n\n  for (const removal of removals) {\n    const verb = removal.action === 'delete' ? 'delete' : 'modify';\n    const answer = await ask(`  ${removal.name} — ${verb} it? (yes/no)> `);\n    if (answer !== 'yes') {\n      io.output(`  skipped ${removal.name} — not touched\\n`);\n      continue;\n    }\n    if (removal.action === 'delete') {\n      unlinkSync(removal.path);\n      io.output(`  deleted ${removal.name}\\n`);\n    } else {\n      writeFileSync(removal.path, removal.content ?? '');\n      io.output(`  cleaned ${removal.name}\\n`);\n    }\n  }\n  io.output(`Done.\\n`);\n  return 0;\n}\n"]}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"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","sourcesContent":["import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\n\nimport { CliUsageError } from '../errors.ts';\nimport { nodeCommand, portablePath, shimScriptPath, smeltBinPath } from '../harness/paths.ts';\nimport { hasShim, TIER_HONESTY } from '../harness/profile.ts';\nimport type {\n  HarnessInstallContext,\n  HarnessJsonHooks,\n  HarnessProfile,\n} from '../harness/profile.ts';\nimport {\n  GUARD_EVENTS,\n  GUARD_ONLY_FILES,\n  HARNESSES,\n  harnessById,\n  harnessNames,\n  JSON_HOOK_FILES,\n  LIFECYCLE_EVENTS,\n  lifecycleHarnesses,\n  MANAGED_EVENTS,\n} from '../harness/registry.ts';\nimport {\n  instructionSnippet,\n  OURS_TOKEN,\n  SNIPPET_END_MD,\n  SNIPPET_START_MD,\n} from '../harness/snippet.ts';\nimport { DEFAULT_SUGGESTION_BUDGET_BYTES, DEFAULT_THRESHOLD_BYTES } from '../hooks/guard-core.ts';\nimport type { EnforcementMode } from '../hooks/guard-core.ts';\nimport {\n  editTopLevelProperty,\n  jsonStyle,\n  stripMarkerBlock,\n  upsertMarkerBlock,\n} from '../text/json-edit.ts';\n\nimport { answerReader, CLI_NAME } from './shell.ts';\nimport type { AnswerStream } from './shell.ts';\nimport {\n  CONFIG_FILE_NAME,\n  CONFIG_VERSION,\n  findConfigFile,\n  parseConfig,\n  renderConfig,\n} from './config.ts';\nimport type { SmeltConfig, SmeltConfigHooks } from './config.ts';\n\n/**\n * `smelt hooks install` / `smelt hooks remove` — the multi-harness guard preset.\n *\n * The design: one zero-dependency guard core\n * (`src/hooks/guard-core.ts`), thin per-harness shims mapping each harness's native\n * hook schema onto it, and this installer, which writes the harness config that wires\n * a shim in — plus an instruction-file snippet as belt and braces, because the\n * snippet is also what teaches the model to run `smelt retrieve` after a deny.\n *\n * Every per-harness fact lives in that harness's {@link HarnessProfile}\n * (`src/harness/<id>.ts`), including what to write and how to take it back out. This\n * module owns only what is the *same* for every harness: the hooks merge (which entries\n * are ours, what a re-run replaces), the wizard, and the two plans below — folds over\n * `profile.install`, with no case list of its own. The byte-faithful editing itself —\n * one top-level JSON property, one delimited text block — is `src/text/json-edit.ts`,\n * which knows nothing about harnesses.\n *\n * Harnesses come in three honesty tiers (docs/research/2026-09-02-harness-capability-matrix.md),\n * and which harness sits at which is `HarnessProfile.tier` — read through\n * `harnessesByTier()`, never listed again here:\n *\n *  - **verified** — schemas verified against primary docs and exercised against\n *    recorded fixtures; first-class targets.\n *  - **experimental** — hook schemas mapped from the capability matrix but not yet\n *    smoke-tested green against the real binary. Labelled as such in code, docs, and\n *    this installer's output.\n *  - **advisory** — no usable hook API, so what ships is instructions (and, for\n *    KiloCode, a permissions/MCP sketch). Nothing enforces them, and the output says\n *    so rather than implying a guard exists.\n *\n * The wizard discipline is `smelt init`'s, verbatim: every step accepts `back`,\n * nothing is written until a final confirm that lists every file, and an existing\n * file is never overwritten without an explicit per-file `yes` — guarded by\n * `test/guards/hooks-preset.test.ts`, with mutation `hooks-install-overwrite-without-consent`\n * proving the guard goes red.\n */\n\n/** Where the wizard's bytes come from and go. Injected so `runHooks` tests in-process. */\nexport interface HooksIo {\n  /**\n   * Scripted answers in, one line at a time. Structural on purpose; see\n   * {@link AnswerStream}.\n   */\n  readonly input: AnswerStream;\n  readonly output: (text: string) => void;\n  /** Project directory: detection, config discovery, and every write are relative to it. */\n  readonly cwd: string;\n  /** Home directory for detection only. Tests point it at a temp dir; nothing writes here. */\n  readonly home?: string;\n}\n\nexport { instructionSnippet, SNIPPET_END_MD, SNIPPET_START_MD };\n\n/** A harness whose config directory exists in the project or the home directory. */\nexport function detectedHarnesses(cwd: string, home: string): readonly HarnessProfile[] {\n  return HARNESSES.filter(\n    (profile) =>\n      profile.detect.some((path) => existsSync(join(cwd, path))) ||\n      profile.detectHome.some((path) => existsSync(join(home, path))),\n  );\n}\n\n/* ------------------------------------------------------------------------------------\n * Generated content\n * ---------------------------------------------------------------------------------- */\n\n/** Claude-style hook entry: one command under an optional matcher. */\nfunction commandEntry(matcher: string | undefined, command: string): unknown {\n  return {\n    ...(matcher === undefined ? {} : { matcher }),\n    hooks: [{ type: 'command', command }],\n  };\n}\n\n/**\n * The hook command a harness's entries run: its own shim script, through node.\n *\n * @throws {Error} when a profile declares a JSON hook file but ships no shim — a\n *   registry bug, pinned by `test/guards/harness-registry.test.ts`, not a user error.\n */\nfunction shimCommand(profile: HarnessProfile, cwd: string): string {\n  /* v8 ignore next 5 -- unreachable: pinned by the harness-registry guard */\n  if (!hasShim(profile)) {\n    throw new Error(\n      `smelt: harness \"${profile.id}\" wires a hook command but ships no shim script.`,\n    );\n  }\n  return nodeCommand(cwd, shimScriptPath(profile));\n}\n\n/**\n * One harness's hook entries: the guard under each matcher its schema spells, plus\n * the session-lifecycle hooks for the harnesses whose schema carries them. Every\n * toggle the wizard offers is a key that is present or absent here — an absent key is\n * how a re-run turns a toggle *off*, because the merge deletes what it no longer sees.\n *\n * The two `SessionStart` toggles — the opening map and the instruction-file lint —\n * are **concatenated into one array**, not spread as two objects. Spreading would put\n * the same computed key twice in one literal, and the second would silently replace\n * the first: turning the lint on would turn the map off, with no error anywhere. It is\n * the shape of bug this file exists to refuse, one layer up from the config it writes.\n */\nfunction jsonHookEvents(\n  step: HarnessJsonHooks,\n  ctx: HarnessInstallContext,\n  command: string,\n): Record<string, readonly unknown[]> {\n  // The trailing shell comment tags the entry as this installer's (see isOursEntry):\n  // a bare `cli/bin.js` substring would also match some other npm CLI's built binary.\n  const stats = `${nodeCommand(ctx.cwd, smeltBinPath(), 'stats')} 2>/dev/null || true # ${OURS_TOKEN}`;\n  const map = `${nodeCommand(\n    ctx.cwd,\n    smeltBinPath(),\n    `${MAP_ON_START_ARGS} --budget ${String(ctx.budgetBytes)} --cache .smelt/tags`,\n  )} 2>/dev/null || true # ${OURS_TOKEN}`;\n  const lint = `${nodeCommand(\n    ctx.cwd,\n    smeltBinPath(),\n    AGENTS_LINT_ARGS,\n  )} 2>/dev/null || true # ${OURS_TOKEN}`;\n\n  const sessionStart = [\n    ...(ctx.mapOnStart ? [commandEntry(SESSION_START_MATCHER, map)] : []),\n    ...(ctx.lintOnStart ? [commandEntry(SESSION_START_MATCHER, lint)] : []),\n  ];\n\n  return {\n    ...(ctx.guard\n      ? {\n          [step.event]: step.matchers.map((matcher) =>\n            step.entry === 'bare-command' ? { command } : commandEntry(matcher, command),\n          ),\n        }\n      : {}),\n    ...(step.lifecycle && ctx.statsOnStop\n      ? { [LIFECYCLE_EVENTS.stats]: [commandEntry(undefined, stats)] }\n      : {}),\n    ...(step.lifecycle && sessionStart.length > 0 ? { [LIFECYCLE_EVENTS.map]: sessionStart } : {}),\n  };\n}\n\n/** The matcher both `SessionStart` entries fire under — a session opening, however. */\nconst SESSION_START_MATCHER = 'startup|resume|clear|compact';\n\n/**\n * The two `SessionStart` commands' distinguishing arguments, and **the substrings a\n * re-run recognises each entry by**. Spelled once so the writer and the reader cannot\n * drift: `presetToggles` tells the two entries apart by the command each one runs, and\n * a wizard that wrote `agents lint .` while its reader looked for `agents lint` would\n * read every re-run's lint toggle back as off and quietly delete it.\n */\nconst MAP_ON_START_ARGS = 'map .';\nexport const AGENTS_LINT_ARGS = 'agents lint .';\n\n/**\n * True for a hook entry this installer wrote. Matched on the shim script paths and the\n * `smelt:hooks` token the stats/map commands carry — never on a substring as generic\n * as `cli/bin.js`, which another npm CLI's built binary could share: remove and\n * re-install may only ever touch entries that are provably smelt's.\n */\nfunction isOursEntry(entry: unknown): boolean {\n  const text = JSON.stringify(entry) ?? '';\n  return text.includes('hooks/shims/') || text.includes(OURS_TOKEN);\n}\n\n/**\n * Merge our hook entries into a JSON settings file, preserving everything foreign\n * **byte-faithfully**: the merged `hooks` value is spliced into the original text, so\n * unknown top-level keys, string escapes, number spellings, indentation and key order\n * outside the `hooks` property ride through verbatim (an installer\n * that reformats somebody's settings file has edited what it was never asked to).\n * Inside `hooks`, unmanaged events and other people's entries under managed events\n * are preserved; our previous entries are replaced (that is what makes a re-run edit\n * toggles), and events left with no entries disappear. A semantic no-op returns the\n * input text unchanged. Returns `undefined` when the existing file is not a JSON\n * object — the caller skips the file rather than clobbering something it cannot\n * understand.\n */\nexport function mergeJsonHooks(\n  existingText: string | undefined,\n  events: Record<string, readonly unknown[]>,\n  shape: { readonly version?: number } = {},\n): string | undefined {\n  let root: Record<string, unknown> = {};\n  if (existingText !== undefined) {\n    try {\n      const parsed: unknown = JSON.parse(existingText);\n      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;\n      root = parsed as Record<string, unknown>;\n    } catch {\n      return undefined;\n    }\n  }\n  const hooksValue = root['hooks'];\n  const existingHooks =\n    typeof hooksValue === 'object' && hooksValue !== null && !Array.isArray(hooksValue)\n      ? (hooksValue as Record<string, unknown>)\n      : undefined;\n  const hooks = { ...existingHooks };\n\n  for (const event of MANAGED_EVENTS) {\n    const existing = Array.isArray(hooks[event]) ? (hooks[event] as unknown[]) : [];\n    const foreign = existing.filter((entry) => !isOursEntry(entry));\n    const ours = events[event] ?? [];\n    const merged = [...foreign, ...ours];\n    if (merged.length > 0) hooks[event] = merged;\n    else delete hooks[event];\n  }\n\n  const mergedHooks = Object.keys(hooks).length > 0 ? hooks : undefined;\n\n  // A brand-new file: nothing to preserve, render fresh two-space JSON.\n  if (existingText === undefined) {\n    const fresh: Record<string, unknown> = {};\n    if (mergedHooks !== undefined) fresh['hooks'] = mergedHooks;\n    if (shape.version !== undefined) fresh['version'] = shape.version;\n    return `${JSON.stringify(fresh, null, 2)}\\n`;\n  }\n\n  const hooksChanged =\n    JSON.stringify(existingHooks ?? null) !== JSON.stringify(mergedHooks ?? null);\n  const needsVersion = shape.version !== undefined && root['version'] === undefined;\n  if (!hooksChanged && !needsVersion) return existingText;\n\n  // The style is read once, off the original: a second edit must match the first.\n  const style = jsonStyle(existingText);\n  let text: string | undefined = existingText;\n\n  if (hooksChanged) {\n    text = editTopLevelProperty(text, 'hooks', mergedHooks, style);\n    /* v8 ignore next -- unreachable: JSON.parse accepted the same text above */\n    if (text === undefined) return undefined;\n  }\n  if (needsVersion) {\n    text = editTopLevelProperty(text, 'version', shape.version, style);\n    /* v8 ignore next -- unreachable: every splice above keeps the text valid JSON */\n    if (text === undefined) return undefined;\n  }\n  return text;\n}\n\n/* ------------------------------------------------------------------------------------\n * Planning\n * ---------------------------------------------------------------------------------- */\n\ninterface PlannedFile {\n  /** Display path, relative to the project. */\n  readonly name: string;\n  readonly path: string;\n  readonly content: string;\n  readonly exists: boolean;\n  readonly unchanged: boolean;\n  /** chmod after writing (the cline hook must be executable). */\n  readonly mode?: number;\n}\n\ninterface SkippedFile {\n  readonly name: string;\n  readonly why: string;\n}\n\ninterface PlannedRemoval {\n  readonly name: string;\n  readonly path: string;\n  /** `'delete'` removes the file; `'modify'` writes `content` (ours stripped out). */\n  readonly action: 'delete' | 'modify';\n  readonly content?: string;\n}\n\nexport interface HooksChoices {\n  harnesses: HarnessProfile[];\n  guard: boolean;\n  statsOnStop: boolean;\n  mapOnStart: boolean;\n  lintOnStart: boolean;\n  enforcement: EnforcementMode;\n  thresholdBytes: number;\n}\n\ninterface InstallPlan {\n  readonly files: readonly PlannedFile[];\n  readonly skipped: readonly SkippedFile[];\n  readonly notes: readonly string[];\n}\n\nfunction planFile(cwd: string, name: string, content: string, mode?: number): PlannedFile {\n  const path = join(cwd, name);\n  const exists = existsSync(path);\n  const unchanged = exists && readFileSync(path, 'utf8') === content;\n  return { name, path, content, exists, unchanged, ...(mode === undefined ? {} : { mode }) };\n}\n\nfunction readIfExists(path: string): string | undefined {\n  return existsSync(path) ? readFileSync(path, 'utf8') : undefined;\n}\n\n/**\n * Every file `install` would write, computed against the current disk state — pure\n * planning, nothing written. A fold over each chosen profile's `install` list and its\n * instruction layer; all per-harness knowledge is in the profiles. Shared instruction\n * files (several harnesses read AGENTS.md) are planned once.\n *\n * @throws {CliUsageError} when an existing `smelt.config.json` is malformed — the\n *   same refusal every other subcommand makes; an installer that guessed around a\n *   broken config would write settings the guard then ignores.\n */\nexport function planInstall(cwd: string, choices: HooksChoices): InstallPlan {\n  const files = new Map<string, PlannedFile>();\n  const skipped: SkippedFile[] = [];\n  const notes: string[] = [];\n\n  // -- smelt.config.json: the guard's runtime settings live here, not in any harness\n  // file, so every shim reads one source of truth.\n  const configPath = findConfigFile(cwd) ?? join(cwd, CONFIG_FILE_NAME);\n  const existingConfig =\n    readIfExists(configPath) === undefined\n      ? undefined\n      : parseConfig(readFileSync(configPath, 'utf8'), configPath);\n  const hooksBlock: SmeltConfigHooks = {\n    thresholdBytes: choices.thresholdBytes,\n    enforcement: choices.enforcement,\n  };\n  const budgetBytes = existingConfig?.defaultBudgetBytes ?? DEFAULT_SUGGESTION_BUDGET_BYTES;\n  files.set(configPath, {\n    name: portablePath(cwd, configPath),\n    path: configPath,\n    content: renderConfigWithHooks(existingConfig, hooksBlock),\n    exists: existsSync(configPath),\n    unchanged: readIfExists(configPath) === renderConfigWithHooks(existingConfig, hooksBlock),\n  });\n\n  const ctx: HarnessInstallContext = {\n    cwd,\n    guard: choices.guard,\n    statsOnStop: choices.statsOnStop,\n    mapOnStart: choices.mapOnStart,\n    lintOnStart: choices.lintOnStart,\n    thresholdBytes: choices.thresholdBytes,\n    budgetBytes,\n  };\n  const snippet = instructionSnippet(choices.thresholdBytes, budgetBytes);\n\n  const planJsonHooks = (\n    name: string,\n    events: Record<string, readonly unknown[]>,\n    shape: { readonly version?: number } = {},\n  ): void => {\n    const path = join(cwd, name);\n    // Nothing to install and nothing to strip: don't create an empty hooks file.\n    if (Object.keys(events).length === 0 && !existsSync(path)) return;\n    const merged = mergeJsonHooks(readIfExists(path), events, shape);\n    if (merged === undefined) {\n      skipped.push({\n        name,\n        why: 'exists but is not a JSON object — fix or remove it, then re-run',\n      });\n      return;\n    }\n    files.set(path, planFile(cwd, name, merged));\n  };\n\n  const planBlockFile = (\n    name: string,\n    block: string,\n    start: string,\n    end: string,\n    skipWhen?: { readonly contains: string; readonly why: string },\n  ): void => {\n    const path = join(cwd, name);\n    if (files.has(path)) return; // a shared file (AGENTS.md), already planned\n    const existing = readIfExists(path);\n    // A file that already carries its owner's version of what this block does is\n    // theirs to edit, not ours: say so, and touch nothing.\n    if (\n      skipWhen !== undefined &&\n      existing !== undefined &&\n      !existing.includes(start) &&\n      existing.includes(skipWhen.contains)\n    ) {\n      skipped.push({ name, why: skipWhen.why });\n      return;\n    }\n    files.set(path, planFile(cwd, name, upsertMarkerBlock(existing, block, start, end)));\n  };\n\n  for (const profile of choices.harnesses) {\n    for (const step of profile.install) {\n      switch (step.kind) {\n        case 'json-hooks':\n          planJsonHooks(\n            step.file,\n            jsonHookEvents(step, ctx, shimCommand(profile, cwd)),\n            step.shape ?? {},\n          );\n          break;\n        case 'marker-block':\n          planBlockFile(step.file, step.block(ctx), step.start, step.end, step.skipWhen);\n          break;\n        case 'own-file':\n          if (step.guardOnly && !ctx.guard) break;\n          files.set(join(cwd, step.file), planFile(cwd, step.file, step.content(ctx), step.mode));\n          break;\n      }\n    }\n\n    if (profile.instructions === 'snippet') {\n      planBlockFile(profile.instructionFile, snippet, SNIPPET_START_MD, SNIPPET_END_MD);\n    } else {\n      files.set(\n        join(cwd, profile.instructionFile),\n        planFile(cwd, profile.instructionFile, profile.instructions(ctx)),\n      );\n    }\n\n    for (const caveat of profile.caveats) notes.push(`${profile.name}: ${caveat}`);\n  }\n\n  return { files: [...files.values()], skipped, notes };\n}\n\n/** Where the installed config points the persistent store, relative to the config file. */\nexport const DEFAULT_STORE_DIR = '.smelt/store';\n\n/**\n * Existing config re-rendered with the hooks block, other fields carried verbatim —\n * except that a config with **no** store block gains a directory store. The deny\n * reasons and the instruction snippet teach `smelt retrieve <hash>`, and retrieval\n * across processes needs a persistent store (`smelt retrieve` refuses a memory\n * store, exit 2) — an install whose own guard promises a command the installed\n * config cannot run would be the exact silent-failure shape this project refuses.\n * An *explicit* `{\"kind\":\"memory\"}` is respected; the guard then conditions its\n * retrieve promise on the store kind instead (`retrieveSentence` in guard-core).\n *\n * That store injection is this verb's **policy**, which is why it lives here; the\n * bytes are written by `renderConfig` in `config.ts`, the one writer, so a key added\n * to the schema reaches this file and `init`'s together or not at all.\n *\n * \"Carried verbatim\" is spelled as a spread rather than as a list of the fields to\n * copy, and that is load-bearing: the list version silently dropped every key nobody\n * remembered to add to it — `agents` was added to the schema and this function kept\n * writing configs without it, which is a setting the user believed was in force,\n * caught by `test/guards/config-writer.test.ts`. Only the two fields this verb\n * actually decides are named.\n */\nexport function renderConfigWithHooks(\n  existing: SmeltConfig | undefined,\n  hooks: SmeltConfigHooks,\n): string {\n  return renderConfig({\n    ...existing,\n    smeltConfig: CONFIG_VERSION,\n    store: existing?.store ?? { kind: 'directory', path: DEFAULT_STORE_DIR },\n    hooks,\n  });\n}\n\n/**\n * Everything `remove` would delete or strip, computed against the current disk state.\n * The mirror image of {@link planInstall}, over the same data: each install step's\n * kind is also how it comes back out — a JSON hook file is strip-merged, a marker\n * block is stripped, a file that is entirely ours is deleted.\n */\nexport function planRemove(\n  cwd: string,\n  harnesses: readonly HarnessProfile[],\n): readonly PlannedRemoval[] {\n  const removals = new Map<string, PlannedRemoval>();\n\n  const planJsonStrip = (name: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined) return;\n    const stripped = mergeJsonHooks(existing, {});\n    if (stripped === undefined || stripped === existing) return;\n    const remains: unknown = JSON.parse(stripped);\n    const empty =\n      typeof remains === 'object' &&\n      remains !== null &&\n      Object.keys(remains as Record<string, unknown>).filter((key) => key !== 'version').length ===\n        0;\n    removals.set(\n      path,\n      empty && existing.includes('hooks')\n        ? { name, path, action: 'delete' }\n        : { name, path, action: 'modify', content: stripped },\n    );\n  };\n\n  const planBlockStrip = (name: string, start: string, end: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined || !existing.includes(start)) return;\n    const stripped = stripMarkerBlock(existing, start, end);\n    removals.set(\n      path,\n      stripped === undefined\n        ? { name, path, action: 'delete' }\n        : { name, path, action: 'modify', content: stripped },\n    );\n  };\n\n  const planWholeFileDelete = (name: string): void => {\n    const path = join(cwd, name);\n    const existing = readIfExists(path);\n    if (existing === undefined || !existing.includes(OURS_TOKEN)) return;\n    removals.set(path, { name, path, action: 'delete' });\n  };\n\n  for (const profile of harnesses) {\n    for (const step of profile.install) {\n      switch (step.kind) {\n        case 'json-hooks':\n          planJsonStrip(step.file);\n          break;\n        case 'marker-block':\n          planBlockStrip(step.file, step.start, step.end);\n          break;\n        case 'own-file':\n          planWholeFileDelete(step.file);\n          break;\n      }\n    }\n    if (profile.instructions === 'snippet') {\n      planBlockStrip(profile.instructionFile, SNIPPET_START_MD, SNIPPET_END_MD);\n    } else {\n      planWholeFileDelete(profile.instructionFile);\n    }\n  }\n\n  return [...removals.values()];\n}\n\n/* ------------------------------------------------------------------------------------\n * The wizard\n * ---------------------------------------------------------------------------------- */\n\ntype Asker = (prompt: string) => Promise<string>;\n\n/**\n * `smelt hooks <install|remove>`, start to finish. The same testability pattern as\n * `runInit`: a pure function over an input/output pair, exit code returned.\n */\nexport async function runHooks(\n  action: 'install' | 'remove',\n  harnessFlag: string | undefined,\n  io: HooksIo,\n): Promise<number> {\n  // Same adapter, same reason, as `runInit` — see the note on `answerReader`.\n  const lines = answerReader(io.input);\n  const ask = async (prompt: string): Promise<string> => {\n    io.output(prompt);\n    const next = await lines.next();\n    if (next === undefined) {\n      throw new CliUsageError(\n        `${CLI_NAME} hooks: input ended before the wizard finished. ` +\n          `Files already confirmed and written stay; nothing further was written.`,\n      );\n    }\n    return next.trim();\n  };\n\n  try {\n    return action === 'install'\n      ? await installFlow(io, ask, harnessFlag)\n      : await removeFlow(io, ask, harnessFlag);\n  } finally {\n    await lines.release();\n  }\n}\n\nfunction resolveHarnessFlag(flag: string): HarnessProfile {\n  const profile = harnessById(flag);\n  if (profile === undefined) {\n    throw new CliUsageError(\n      `${CLI_NAME} hooks: unknown harness \"${flag}\". ` +\n        `Known: ${HARNESSES.map((h) => h.id).join(', ')}.`,\n    );\n  }\n  return profile;\n}\n\nfunction tierLabel(profile: HarnessProfile): string {\n  return `${profile.id.padEnd(12)} ${profile.name.padEnd(14)} [${profile.tier}] — ${TIER_HONESTY[profile.tier]}`;\n}\n\nasync function installFlow(\n  io: HooksIo,\n  ask: Asker,\n  harnessFlag: string | undefined,\n): Promise<number> {\n  const home = io.home ?? homedir();\n  const detected = detectedHarnesses(io.cwd, home);\n\n  io.output(\n    `${CLI_NAME} hooks install — wires the smelt guard into agent-harness hooks.\\n` +\n      `Answer \\`back\\` at any step to return to the previous one. Nothing is written ` +\n      `until you confirm at the end.\\n\\n`,\n  );\n\n  const choices: HooksChoices = {\n    harnesses: harnessFlag !== undefined ? [resolveHarnessFlag(harnessFlag)] : [...detected],\n    ...presetToggles(io.cwd),\n    enforcement: 'deny',\n    thresholdBytes: DEFAULT_THRESHOLD_BYTES,\n  };\n\n  // With --harness the selection step is skipped, so the tier label — and its one\n  // line of honesty about what the tier means — is printed here instead.\n  if (harnessFlag !== undefined) {\n    for (const profile of choices.harnesses) io.output(`  ${tierLabel(profile)}\\n`);\n  }\n\n  const steps: readonly ((io_: HooksIo, ask_: Asker) => Promise<'ok' | 'back'>)[] = [\n    async (io_, ask_) =>\n      harnessFlag !== undefined ? 'ok' : stepHarnesses(io_, ask_, choices, detected),\n    async (io_, ask_) =>\n      stepToggle(io_, ask_, 'PreToolUse size-guard', guardCopy(), choices.guard, (on) => {\n        choices.guard = on;\n      }),\n    async (io_, ask_) =>\n      stepToggle(\n        io_,\n        ask_,\n        'stats on Stop',\n        `\\`smelt stats\\` runs when a session ends — the honest signal (expansion rate) ` +\n          `surfaced where the turn ends. Observation only; never blocks. Wired for the ` +\n          `harnesses whose hooks carry session events (${harnessNames(lifecycleHarnesses())}).`,\n        choices.statsOnStop,\n        (on) => {\n          choices.statsOnStop = on;\n        },\n      ),\n    async (io_, ask_) =>\n      stepToggle(\n        io_,\n        ask_,\n        'repo map on SessionStart',\n        `\\`smelt map . --budget …\\` runs at session start and its output opens the ` +\n          `context — the agent starts oriented. Costs one map build per session. ` +\n          `Wired for the harnesses whose hooks carry session events ` +\n          `(${harnessNames(lifecycleHarnesses())}).`,\n        choices.mapOnStart,\n        (on) => {\n          choices.mapOnStart = on;\n        },\n      ),\n    async (io_, ask_) =>\n      stepToggle(\n        io_,\n        ask_,\n        'instruction-file lint on SessionStart',\n        `\\`smelt agents lint .\\` runs at session start and reports on the AGENTS.md, ` +\n          `CLAUDE.md and GEMINI.md this session is about to load on every request — ` +\n          `bytes per level, and any path or link in them that no longer resolves. ` +\n          `Advisory: it never blocks, and it exits 0 unless you set ` +\n          `agents.budgetBytes in ${CONFIG_FILE_NAME}. Wired for verified-tier ` +\n          `harnesses (Claude Code, Codex).`,\n        choices.lintOnStart,\n        (on) => {\n          choices.lintOnStart = on;\n        },\n      ),\n    async (io_, ask_) => stepEnforcement(io_, ask_, choices),\n    async (io_, ask_) => stepThreshold(io_, ask_, choices),\n  ];\n\n  let index = 0;\n  for (;;) {\n    while (index < steps.length) {\n      const outcome = await steps[index]!(io, ask);\n      if (outcome === 'back') {\n        if (index === 0) io.output(`This is the first step — there is nothing before it.\\n`);\n        else index -= 1;\n      } else {\n        index += 1;\n      }\n    }\n    if (choices.harnesses.length === 0) {\n      io.output(`No harness selected. Nothing to do; nothing was written.\\n`);\n      return 0;\n    }\n    const verdict = await confirmAndInstall(io, ask, choices);\n    if (verdict !== 'back') return 0;\n    index = steps.length - 1;\n  }\n}\n\nfunction guardCopy(): string {\n  return (\n    `Denies raw Reads (and simple \\`cat\\`s) of files over the size threshold, with a ` +\n    `reason naming the exact \\`smelt\\` replacement — the model still sees everything: ` +\n    `smelted first, \\`smelt retrieve\\` for the rest. Windowed reads (offset/limit) ` +\n    `always pass.`\n  );\n}\n\nasync function stepHarnesses(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n  detected: readonly HarnessProfile[],\n): Promise<'ok' | 'back'> {\n  io.output(`\\nHarnesses — detected by their config directories (project or home):\\n`);\n  for (const profile of HARNESSES) {\n    const mark = detected.includes(profile) ? '*' : ' ';\n    io.output(`  ${mark} ${tierLabel(profile)}\\n`);\n  }\n  io.output(`(* = detected here)\\n`);\n  for (;;) {\n    const current = choices.harnesses.map((profile) => profile.id).join(',') || '(none)';\n    const answer = await ask(\n      `install for which? (comma-separated ids, Enter = ${current}, or back)\\n> `,\n    );\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    const ids = answer\n      .split(',')\n      .map((id) => id.trim())\n      .filter((id) => id !== '');\n    const chosen: HarnessProfile[] = [];\n    let bad: string | undefined;\n    for (const id of ids) {\n      const profile = harnessById(id);\n      if (profile === undefined) bad = id;\n      else if (!chosen.includes(profile)) chosen.push(profile);\n    }\n    if (bad !== undefined) {\n      io.output(`Unknown harness \"${bad}\". Known: ${HARNESSES.map((h) => h.id).join(', ')}.\\n`);\n      continue;\n    }\n    choices.harnesses = chosen;\n    return 'ok';\n  }\n}\n\nasync function stepToggle(\n  io: HooksIo,\n  ask: Asker,\n  name: string,\n  copy: string,\n  current: boolean,\n  set: (on: boolean) => void,\n): Promise<'ok' | 'back'> {\n  io.output(`\\n${name} — ${copy}\\n`);\n  for (;;) {\n    const answer = await ask(`${name}? (on/off) [${current ? 'on' : 'off'}] (or back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    if (answer === 'on' || answer === 'off') {\n      set(answer === 'on');\n      return 'ok';\n    }\n    io.output(`on, off, or back.\\n`);\n  }\n}\n\nasync function stepEnforcement(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'ok' | 'back'> {\n  io.output(\n    `\\nEnforcement — what happens when the guard catches an oversized raw read:\\n` +\n      `  1. deny     — refuse with a reason naming the exact replacement command. The\\n` +\n      `                transcript stays truthful; the model runs the replacement itself.\\n` +\n      `  2. rewrite  — on harnesses whose hooks can modify tool input, substitute the\\n` +\n      `                replacement in-flight (grep/cat piped through smelt). Never\\n` +\n      `                silent: the substitution is announced in the decision reason\\n` +\n      `                where the harness has one, on stderr where it does not.\\n` +\n      `                Harnesses that cannot rewrite fall back to deny.\\n`,\n  );\n  for (;;) {\n    const current = choices.enforcement === 'deny' ? '1' : '2';\n    const answer = await ask(`enforcement (1/2) [${current}] (or back)> `);\n    if (answer === 'back') return 'back';\n    const pick = answer === '' ? current : answer;\n    if (pick === '1' || pick === '2') {\n      choices.enforcement = pick === '1' ? 'deny' : 'rewrite';\n      return 'ok';\n    }\n    io.output(`1 for deny, 2 for rewrite, or back.\\n`);\n  }\n}\n\nasync function stepThreshold(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'ok' | 'back'> {\n  io.output(\n    `\\nSize threshold — reads at or under this many bytes always pass. The ${String(\n      DEFAULT_THRESHOLD_BYTES,\n    )}-byte default comes from the measured validation in ` +\n      `docs/research/2026-09-02-agent-enforcement.md § 5.\\n`,\n  );\n  for (;;) {\n    const answer = await ask(`threshold in bytes [${String(choices.thresholdBytes)}] (or back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === '') return 'ok';\n    if (/^\\d+$/.test(answer) && Number(answer) > 0) {\n      choices.thresholdBytes = Number(answer);\n      return 'ok';\n    }\n    io.output(`A whole number of bytes greater than zero, e.g. 8192.\\n`);\n  }\n}\n\n/**\n * A re-run reads the toggles back off what is actually installed — every JSON hook\n * file this installer writes, plus the guard-only shim files, both derived from the\n * registry — so it edits instead of resetting. Harnesses that only wire the guard\n * (gemini, grok, cursor, hermes, opencode, cline) persist no stats/map entries, so\n * after a re-run scoped to them those toggles read back as off; the defaults below\n * apply only when nothing of smelt's is installed at all.\n *\n * The two `SessionStart` toggles share one event, so they are told apart by **the\n * command each entry runs**, not by the key it sits under. Reading `SessionStart` as\n * one boolean would make a re-run with the map on and the lint off write both back —\n * or neither — which is a toggle the user believed they had set.\n */\nfunction presetToggles(\n  cwd: string,\n): Pick<HooksChoices, 'guard' | 'statsOnStop' | 'mapOnStart' | 'lintOnStart'> {\n  const defaults = { guard: true, statsOnStop: true, mapOnStart: false, lintOnStart: false };\n  let anyOurs = false;\n  let guard = false;\n  let statsOnStop = false;\n  let mapOnStart = false;\n  let lintOnStart = false;\n\n  for (const name of JSON_HOOK_FILES) {\n    const text = readIfExists(join(cwd, name));\n    if (text === undefined) continue;\n    let hooks: Record<string, unknown> | undefined;\n    try {\n      const parsed: unknown = JSON.parse(text);\n      const hooksValue =\n        typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)\n          ? (parsed as Record<string, unknown>)['hooks']\n          : undefined;\n      hooks =\n        typeof hooksValue === 'object' && hooksValue !== null && !Array.isArray(hooksValue)\n          ? (hooksValue as Record<string, unknown>)\n          : undefined;\n    } catch {\n      hooks = undefined;\n    }\n    if (hooks === undefined) continue;\n    const installed = hooks;\n    const oursUnder = (event: string): readonly unknown[] =>\n      Array.isArray(installed[event])\n        ? (installed[event] as unknown[]).filter((entry) => isOursEntry(entry))\n        : [];\n    const hasOurs = (event: string): boolean => oursUnder(event).length > 0;\n    /** One of ours under `event` whose command carries `needle`. */\n    const hasOursRunning = (event: string, needle: string): boolean =>\n      oursUnder(event).some((entry) => (JSON.stringify(entry) ?? '').includes(needle));\n    if (!MANAGED_EVENTS.some((event) => hasOurs(event))) continue;\n    anyOurs = true;\n    guard ||= GUARD_EVENTS.some((event) => hasOurs(event));\n    statsOnStop ||= hasOurs(LIFECYCLE_EVENTS.stats);\n    mapOnStart ||= hasOursRunning(LIFECYCLE_EVENTS.map, MAP_ON_START_ARGS);\n    lintOnStart ||= hasOursRunning(LIFECYCLE_EVENTS.lint, AGENTS_LINT_ARGS);\n  }\n\n  for (const name of GUARD_ONLY_FILES) {\n    const text = readIfExists(join(cwd, name));\n    if (text !== undefined && text.includes(OURS_TOKEN)) {\n      anyOurs = true;\n      guard = true;\n    }\n  }\n\n  return anyOurs ? { guard, statsOnStop, mapOnStart, lintOnStart } : defaults;\n}\n\nconst fileLabel = (file: PlannedFile): string => {\n  if (file.unchanged) return 'unchanged — nothing to write';\n  return file.exists ? 'exists — will ask before overwriting' : 'new';\n};\n\nasync function confirmAndInstall(\n  io: HooksIo,\n  ask: Asker,\n  choices: HooksChoices,\n): Promise<'done' | 'back'> {\n  const plan = planInstall(io.cwd, choices);\n\n  io.output(\n    `\\nAbout to write, into ${io.cwd}:\\n` +\n      plan.files.map((file) => `  ${file.name.padEnd(32)} (${fileLabel(file)})\\n`).join('') +\n      plan.skipped.map((skip) => `  ${skip.name.padEnd(32)} (SKIPPED: ${skip.why})\\n`).join('') +\n      `Nothing has been written yet.\\n`,\n  );\n\n  for (;;) {\n    const answer = await ask(`confirm (yes / no / back)> `);\n    if (answer === 'back') return 'back';\n    if (answer === 'no') {\n      io.output(`Nothing was written.\\n`);\n      return 'done';\n    }\n    if (answer === 'yes') break;\n    io.output(`yes to write, no to leave everything untouched, back to change a setting.\\n`);\n  }\n\n  for (const file of plan.files) {\n    if (file.unchanged) {\n      io.output(`  ${file.name} — unchanged, not rewritten\\n`);\n      continue;\n    }\n    if (file.exists) {\n      // The one hard rule, same as `smelt init`: an existing file is never touched\n      // without an explicit per-file yes — not `y`, not Enter, a literal `yes`.\n      const answer = await ask(`  ${file.name} exists — overwrite it? (yes/no)> `);\n      if (answer !== 'yes') {\n        io.output(`  skipped ${file.name} — the existing file was not touched\\n`);\n        continue;\n      }\n    }\n    mkdirSync(dirname(file.path), { recursive: true });\n    writeFileSync(file.path, file.content);\n    if (file.mode !== undefined) chmodSync(file.path, file.mode);\n    io.output(`  wrote ${file.name}\\n`);\n  }\n\n  for (const note of plan.notes) io.output(`note: ${note}\\n`);\n  io.output(\n    `Done. Re-run \\`${CLI_NAME} hooks install\\` to edit toggles; ` +\n      `\\`${CLI_NAME} hooks remove\\` takes it all back out.\\n`,\n  );\n  return 'done';\n}\n\nasync function removeFlow(\n  io: HooksIo,\n  ask: Asker,\n  harnessFlag: string | undefined,\n): Promise<number> {\n  const harnesses = harnessFlag !== undefined ? [resolveHarnessFlag(harnessFlag)] : [...HARNESSES];\n  const removals = planRemove(io.cwd, harnesses);\n\n  if (removals.length === 0) {\n    io.output(`${CLI_NAME} hooks remove: nothing of smelt's found to remove in ${io.cwd}.\\n`);\n    return 0;\n  }\n\n  io.output(\n    `${CLI_NAME} hooks remove — takes smelt's hook wiring back out.\\n\\nPlanned:\\n` +\n      removals\n        .map(\n          (removal) =>\n            `  ${removal.name.padEnd(32)} (${\n              removal.action === 'delete' ? 'delete' : 'remove smelt entries, keep the rest'\n            })\\n`,\n        )\n        .join('') +\n      `${CONFIG_FILE_NAME} is left untouched — its hooks block is your config now; ` +\n      `edit or remove it there.\\nNothing has been changed yet.\\n`,\n  );\n\n  for (;;) {\n    const answer = await ask(`confirm (yes / no)> `);\n    if (answer === 'no') {\n      io.output(`Nothing was changed.\\n`);\n      return 0;\n    }\n    if (answer === 'yes') break;\n    io.output(`yes to proceed, no to leave everything untouched.\\n`);\n  }\n\n  for (const removal of removals) {\n    const verb = removal.action === 'delete' ? 'delete' : 'modify';\n    const answer = await ask(`  ${removal.name} — ${verb} it? (yes/no)> `);\n    if (answer !== 'yes') {\n      io.output(`  skipped ${removal.name} — not touched\\n`);\n      continue;\n    }\n    if (removal.action === 'delete') {\n      unlinkSync(removal.path);\n      io.output(`  deleted ${removal.name}\\n`);\n    } else {\n      writeFileSync(removal.path, removal.content ?? '');\n      io.output(`  cleaned ${removal.name}\\n`);\n    }\n  }\n  io.output(`Done.\\n`);\n  return 0;\n}\n"]}

package/dist/cli/hooks.js

@@ -4,9 +4,10 @@ import { dirname, join } from 'node:path';
 import { CliUsageError } from '../errors.js';
 import { nodeCommand, portablePath, shimScriptPath, smeltBinPath } from '../harness/paths.js';
 import { hasShim, TIER_HONESTY } from '../harness/profile.js';
-import { GUARD_EVENTS, GUARD_ONLY_FILES, HARNESSES, harnessById, JSON_HOOK_FILES, LIFECYCLE_EVENTS, MANAGED_EVENTS, } from '../harness/registry.js';
+import { GUARD_EVENTS, GUARD_ONLY_FILES, HARNESSES, harnessById, harnessNames, JSON_HOOK_FILES, LIFECYCLE_EVENTS, lifecycleHarnesses, MANAGED_EVENTS, } from '../harness/registry.js';
 import { instructionSnippet, OURS_TOKEN, SNIPPET_END_MD, SNIPPET_START_MD, } from '../harness/snippet.js';
 import { DEFAULT_SUGGESTION_BUDGET_BYTES, DEFAULT_THRESHOLD_BYTES } from '../hooks/guard-core.js';
+import { editTopLevelProperty, jsonStyle, stripMarkerBlock, upsertMarkerBlock, } from '../text/json-edit.js';
 import { answerReader, CLI_NAME } from './shell.js';
 import { CONFIG_FILE_NAME, CONFIG_VERSION, findConfigFile, parseConfig, renderConfig, } from './config.js';
 export { instructionSnippet, SNIPPET_END_MD, SNIPPET_START_MD };
@@ -40,15 +41,26 @@ function shimCommand(profile, cwd) {
 }
 /**
  * One harness's hook entries: the guard under each matcher its schema spells, plus
- * the two session-lifecycle hooks for the harnesses whose schema carries them. Every
+ * the session-lifecycle hooks for the harnesses whose schema carries them. Every
  * toggle the wizard offers is a key that is present or absent here — an absent key is
  * how a re-run turns a toggle *off*, because the merge deletes what it no longer sees.
+ *
+ * The two `SessionStart` toggles — the opening map and the instruction-file lint —
+ * are **concatenated into one array**, not spread as two objects. Spreading would put
+ * the same computed key twice in one literal, and the second would silently replace
+ * the first: turning the lint on would turn the map off, with no error anywhere. It is
+ * the shape of bug this file exists to refuse, one layer up from the config it writes.
  */
 function jsonHookEvents(step, ctx, command) {
     // The trailing shell comment tags the entry as this installer's (see isOursEntry):
     // a bare `cli/bin.js` substring would also match some other npm CLI's built binary.
     const stats = `${nodeCommand(ctx.cwd, smeltBinPath(), 'stats')} 2>/dev/null || true # ${OURS_TOKEN}`;
-    const map = `${nodeCommand(ctx.cwd, smeltBinPath(), `map . --budget ${String(ctx.budgetBytes)} --cache .smelt/tags`)} 2>/dev/null || true # ${OURS_TOKEN}`;
+    const map = `${nodeCommand(ctx.cwd, smeltBinPath(), `${MAP_ON_START_ARGS} --budget ${String(ctx.budgetBytes)} --cache .smelt/tags`)} 2>/dev/null || true # ${OURS_TOKEN}`;
+    const lint = `${nodeCommand(ctx.cwd, smeltBinPath(), AGENTS_LINT_ARGS)} 2>/dev/null || true # ${OURS_TOKEN}`;
+    const sessionStart = [
+        ...(ctx.mapOnStart ? [commandEntry(SESSION_START_MATCHER, map)] : []),
+        ...(ctx.lintOnStart ? [commandEntry(SESSION_START_MATCHER, lint)] : []),
+    ];
     return {
         ...(ctx.guard
             ? {
@@ -58,11 +70,20 @@ function jsonHookEvents(step, ctx, command) {
         ...(step.lifecycle && ctx.statsOnStop
             ? { [LIFECYCLE_EVENTS.stats]: [commandEntry(undefined, stats)] }
             : {}),
-        ...(step.lifecycle && ctx.mapOnStart
-            ? { [LIFECYCLE_EVENTS.map]: [commandEntry('startup|resume|clear|compact', map)] }
-            : {}),
+        ...(step.lifecycle && sessionStart.length > 0 ? { [LIFECYCLE_EVENTS.map]: sessionStart } : {}),
     };
 }
+/** The matcher both `SessionStart` entries fire under — a session opening, however. */
+const SESSION_START_MATCHER = 'startup|resume|clear|compact';
+/**
+ * The two `SessionStart` commands' distinguishing arguments, and **the substrings a
+ * re-run recognises each entry by**. Spelled once so the writer and the reader cannot
+ * drift: `presetToggles` tells the two entries apart by the command each one runs, and
+ * a wizard that wrote `agents lint .` while its reader looked for `agents lint` would
+ * read every re-run's lint toggle back as off and quietly delete it.
+ */
+const MAP_ON_START_ARGS = 'map .';
+export const AGENTS_LINT_ARGS = 'agents lint .';
 /**
  * True for a hook entry this installer wrote. Matched on the shim script paths and the
  * `smelt:hooks` token the stats/map commands carry — never on a substring as generic
@@ -128,176 +149,23 @@ export function mergeJsonHooks(existingText, events, shape = {}) {
     const needsVersion = shape.version !== undefined && root['version'] === undefined;
     if (!hooksChanged && !needsVersion)
         return existingText;
-    const newline = existingText.includes('\r\n') ? '\r\n' : '\n';
-    const indent = /\n([ \t]+)"/.exec(existingText)?.[1] ?? '  ';
+    // The style is read once, off the original: a second edit must match the first.
+    const style = jsonStyle(existingText);
     let text = existingText;
     if (hooksChanged) {
-        const scan = scanJsonTopLevel(text);
+        text = editTopLevelProperty(text, 'hooks', mergedHooks, style);
         /* v8 ignore next -- unreachable: JSON.parse accepted the same text above */
-        if (scan === undefined)
+        if (text === undefined)
             return undefined;
-        const property = scan.properties.find((candidate) => candidate.key === 'hooks');
-        if (mergedHooks === undefined) {
-            if (property !== undefined)
-                text = removeJsonProperty(text, scan, property);
-        }
-        else {
-            const rendered = renderJsonValue(mergedHooks, indent, newline);
-            text =
-                property !== undefined
-                    ? `${text.slice(0, property.valueStart)}${rendered}${text.slice(property.valueEnd)}`
-                    : insertJsonProperty(text, scan, 'hooks', rendered, indent, newline);
-        }
     }
     if (needsVersion) {
-        const scan = scanJsonTopLevel(text);
+        text = editTopLevelProperty(text, 'version', shape.version, style);
         /* v8 ignore next -- unreachable: every splice above keeps the text valid JSON */
-        if (scan === undefined)
+        if (text === undefined)
             return undefined;
-        text = insertJsonProperty(text, scan, 'version', JSON.stringify(shape.version), indent, newline);
     }
     return text;
 }
-/**
- * Locate the top-level properties of a JSON object *in its source text*, so one
- * property can be replaced, inserted or removed while every other byte of the file
- * rides through verbatim. `undefined` when the text is not an object — callers have
- * already `JSON.parse`d it, so that is belt and braces, not a validator.
- */
-function scanJsonTopLevel(text) {
-    let i = skipJsonWhitespace(text, 0);
-    if (text[i] !== '{')
-        return undefined;
-    const open = i;
-    i = skipJsonWhitespace(text, i + 1);
-    const properties = [];
-    if (text[i] === '}')
-        return { open, close: i, properties };
-    for (;;) {
-        if (text[i] !== '"')
-            return undefined;
-        const keyStart = i;
-        const keyEnd = skipJsonString(text, i);
-        if (keyEnd === undefined)
-            return undefined;
-        const key = JSON.parse(text.slice(keyStart, keyEnd));
-        i = skipJsonWhitespace(text, keyEnd);
-        if (text[i] !== ':')
-            return undefined;
-        const valueStart = skipJsonWhitespace(text, i + 1);
-        const valueEnd = skipJsonValue(text, valueStart);
-        if (valueEnd === undefined)
-            return undefined;
-        properties.push({ key, keyStart, valueStart, valueEnd });
-        i = skipJsonWhitespace(text, valueEnd);
-        if (text[i] === ',') {
-            i = skipJsonWhitespace(text, i + 1);
-            continue;
-        }
-        if (text[i] === '}')
-            return { open, close: i, properties };
-        return undefined;
-    }
-}
-function skipJsonWhitespace(text, from) {
-    let i = from;
-    while (i < text.length && ' \t\r\n'.includes(text[i]))
-        i += 1;
-    return i;
-}
-/** `from` points at `"`; returns the offset one past the closing quote. */
-function skipJsonString(text, from) {
-    let i = from + 1;
-    while (i < text.length) {
-        if (text[i] === '\\')
-            i += 2;
-        else if (text[i] === '"')
-            return i + 1;
-        else
-            i += 1;
-    }
-    return undefined;
-}
-function skipJsonValue(text, from) {
-    const first = text[from];
-    if (first === '"')
-        return skipJsonString(text, from);
-    if (first === '{' || first === '[') {
-        let depth = 0;
-        let i = from;
-        while (i < text.length) {
-            const ch = text[i];
-            if (ch === '"') {
-                const end = skipJsonString(text, i);
-                if (end === undefined)
-                    return undefined;
-                i = end;
-                continue;
-            }
-            if (ch === '{' || ch === '[')
-                depth += 1;
-            else if (ch === '}' || ch === ']') {
-                depth -= 1;
-                if (depth === 0)
-                    return i + 1;
-            }
-            i += 1;
-        }
-        return undefined;
-    }
-    // number / true / false / null
-    let i = from;
-    while (i < text.length && !',}] \t\r\n'.includes(text[i]))
-        i += 1;
-    return i > from ? i : undefined;
-}
-/** A JSON value indented for embedding at a top-level property position. */
-function renderJsonValue(value, indent, newline) {
-    return JSON.stringify(value, null, indent).split('\n').join(`${newline}${indent}`);
-}
-function removeJsonProperty(text, scan, property) {
-    const index = scan.properties.indexOf(property);
-    const next = scan.properties[index + 1];
-    if (next !== undefined) {
-        // Delete through the separating comma and whitespace, up to the next key.
-        return text.slice(0, property.keyStart) + text.slice(next.keyStart);
-    }
-    const previous = scan.properties[index - 1];
-    // Last (or only) property: delete the preceding comma (if any) with it.
-    const from = previous !== undefined ? previous.valueEnd : scan.open + 1;
-    return text.slice(0, from) + text.slice(property.valueEnd);
-}
-function insertJsonProperty(text, scan, key, renderedValue, indent, newline) {
-    const entry = `${JSON.stringify(key)}: ${renderedValue}`;
-    if (scan.properties.length === 0) {
-        return `${text.slice(0, scan.open + 1)}${newline}${indent}${entry}${newline}${text.slice(scan.close)}`;
-    }
-    const last = scan.properties[scan.properties.length - 1];
-    return `${text.slice(0, last.valueEnd)},${newline}${indent}${entry}${text.slice(last.valueEnd)}`;
-}
-/** Replace this installer's marker block in `existingText`, or append it. */
-export function upsertMarkerBlock(existingText, block, start, end) {
-    if (existingText === undefined || existingText.trim() === '')
-        return block;
-    const startIndex = existingText.indexOf(start);
-    const endIndex = existingText.indexOf(end);
-    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-        const before = existingText.slice(0, startIndex);
-        const after = existingText.slice(endIndex + end.length).replace(/^\n/, '');
-        return `${before}${block}${after}`;
-    }
-    return `${existingText.replace(/\n*$/, '\n\n')}${block}`;
-}
-/** Remove the marker block. `undefined` when nothing (or only whitespace) remains. */
-export function stripMarkerBlock(existingText, start, end) {
-    const startIndex = existingText.indexOf(start);
-    const endIndex = existingText.indexOf(end);
-    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex)
-        return existingText;
-    const stripped = existingText.slice(0, startIndex).replace(/\n+$/, '\n') +
-        existingText.slice(endIndex + end.length).replace(/^\n+/, '');
-    return stripped.trim() === '' ? undefined : stripped;
-}
 function planFile(cwd, name, content, mode) {
     const path = join(cwd, name);
     const exists = existsSync(path);
@@ -344,6 +212,7 @@ export function planInstall(cwd, choices) {
         guard: choices.guard,
         statsOnStop: choices.statsOnStop,
         mapOnStart: choices.mapOnStart,
+        lintOnStart: choices.lintOnStart,
         thresholdBytes: choices.thresholdBytes,
         budgetBytes,
     };
@@ -421,14 +290,18 @@ export const DEFAULT_STORE_DIR = '.smelt/store';
  * That store injection is this verb's **policy**, which is why it lives here; the
  * bytes are written by `renderConfig` in `config.ts`, the one writer, so a key added
  * to the schema reaches this file and `init`'s together or not at all.
+ *
+ * "Carried verbatim" is spelled as a spread rather than as a list of the fields to
+ * copy, and that is load-bearing: the list version silently dropped every key nobody
+ * remembered to add to it — `agents` was added to the schema and this function kept
+ * writing configs without it, which is a setting the user believed was in force,
+ * caught by `test/guards/config-writer.test.ts`. Only the two fields this verb
+ * actually decides are named.
  */
 export function renderConfigWithHooks(existing, hooks) {
     return renderConfig({
+        ...existing,
         smeltConfig: CONFIG_VERSION,
-        ...(existing?.defaultBudgetBytes === undefined
-            ? {}
-            : { defaultBudgetBytes: existing.defaultBudgetBytes }),
-        ...(existing?.strategy === undefined ? {} : { strategy: existing.strategy }),
         store: existing?.store ?? { kind: 'directory', path: DEFAULT_STORE_DIR },
         hooks,
     });
@@ -558,15 +431,24 @@ async function installFlow(io, ask, harnessFlag) {
             choices.guard = on;
         }),
         async (io_, ask_) => stepToggle(io_, ask_, 'stats on Stop', `\`smelt stats\` runs when a session ends — the honest signal (expansion rate) ` +
-            `surfaced where the turn ends. Observation only; never blocks. Wired for ` +
-            `verified-tier harnesses (Claude Code, Codex).`, choices.statsOnStop, (on) => {
+            `surfaced where the turn ends. Observation only; never blocks. Wired for the ` +
+            `harnesses whose hooks carry session events (${harnessNames(lifecycleHarnesses())}).`, choices.statsOnStop, (on) => {
             choices.statsOnStop = on;
         }),
         async (io_, ask_) => stepToggle(io_, ask_, 'repo map on SessionStart', `\`smelt map . --budget …\` runs at session start and its output opens the ` +
             `context — the agent starts oriented. Costs one map build per session. ` +
-            `Wired for verified-tier harnesses (Claude Code, Codex).`, choices.mapOnStart, (on) => {
+            `Wired for the harnesses whose hooks carry session events ` +
+            `(${harnessNames(lifecycleHarnesses())}).`, choices.mapOnStart, (on) => {
             choices.mapOnStart = on;
         }),
+        async (io_, ask_) => stepToggle(io_, ask_, 'instruction-file lint on SessionStart', `\`smelt agents lint .\` runs at session start and reports on the AGENTS.md, ` +
+            `CLAUDE.md and GEMINI.md this session is about to load on every request — ` +
+            `bytes per level, and any path or link in them that no longer resolves. ` +
+            `Advisory: it never blocks, and it exits 0 unless you set ` +
+            `agents.budgetBytes in ${CONFIG_FILE_NAME}. Wired for verified-tier ` +
+            `harnesses (Claude Code, Codex).`, choices.lintOnStart, (on) => {
+            choices.lintOnStart = on;
+        }),
         async (io_, ask_) => stepEnforcement(io_, ask_, choices),
         async (io_, ask_) => stepThreshold(io_, ask_, choices),
     ];
@@ -695,13 +577,19 @@ async function stepThreshold(io, ask, choices) {
  * (gemini, grok, cursor, hermes, opencode, cline) persist no stats/map entries, so
  * after a re-run scoped to them those toggles read back as off; the defaults below
  * apply only when nothing of smelt's is installed at all.
+ *
+ * The two `SessionStart` toggles share one event, so they are told apart by **the
+ * command each entry runs**, not by the key it sits under. Reading `SessionStart` as
+ * one boolean would make a re-run with the map on and the lint off write both back —
+ * or neither — which is a toggle the user believed they had set.
  */
 function presetToggles(cwd) {
-    const defaults = { guard: true, statsOnStop: true, mapOnStart: false };
+    const defaults = { guard: true, statsOnStop: true, mapOnStart: false, lintOnStart: false };
     let anyOurs = false;
     let guard = false;
     let statsOnStop = false;
     let mapOnStart = false;
+    let lintOnStart = false;
     for (const name of JSON_HOOK_FILES) {
         const text = readIfExists(join(cwd, name));
         if (text === undefined)
@@ -723,14 +611,19 @@ function presetToggles(cwd) {
         if (hooks === undefined)
             continue;
         const installed = hooks;
-        const hasOurs = (event) => Array.isArray(installed[event]) &&
-            installed[event].some((entry) => isOursEntry(entry));
+        const oursUnder = (event) => Array.isArray(installed[event])
+            ? installed[event].filter((entry) => isOursEntry(entry))
+            : [];
+        const hasOurs = (event) => oursUnder(event).length > 0;
+        /** One of ours under `event` whose command carries `needle`. */
+        const hasOursRunning = (event, needle) => oursUnder(event).some((entry) => (JSON.stringify(entry) ?? '').includes(needle));
         if (!MANAGED_EVENTS.some((event) => hasOurs(event)))
             continue;
         anyOurs = true;
         guard ||= GUARD_EVENTS.some((event) => hasOurs(event));
-        statsOnStop ||= hasOurs('Stop');
-        mapOnStart ||= hasOurs('SessionStart');
+        statsOnStop ||= hasOurs(LIFECYCLE_EVENTS.stats);
+        mapOnStart ||= hasOursRunning(LIFECYCLE_EVENTS.map, MAP_ON_START_ARGS);
+        lintOnStart ||= hasOursRunning(LIFECYCLE_EVENTS.lint, AGENTS_LINT_ARGS);
     }
     for (const name of GUARD_ONLY_FILES) {
         const text = readIfExists(join(cwd, name));
@@ -739,7 +632,7 @@ function presetToggles(cwd) {
             guard = true;
         }
     }
-    return anyOurs ? { guard, statsOnStop, mapOnStart } : defaults;
+    return anyOurs ? { guard, statsOnStop, mapOnStart, lintOnStart } : defaults;
 }
 const fileLabel = (file) => {
     if (file.unchanged)