llm-wiki-kit 0.2.7 → 0.2.9

package/README.md

@@ -86,10 +86,12 @@ Use Claude Code or Codex normally.
 
 The installed hooks:
 
-- inject functional compact context at session start, instructions loaded, prompt submit, and post-compact time. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, and update status; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
+- inject functional compact context at session start, instructions loaded, and prompt submit. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, update status, and any compact recovery packet; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
 - remove Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces at session start so `llm-wiki/` remains the active wiki implementation
 - record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
+- before compaction, classify the current turn and save a redacted checkpoint for meaningful or durable work; durable candidates also get a maintenance queue item
+- after compaction, store the redacted compact summary only; if pre-compact preservation failed, prepare a recovery packet for the next legal model-visible context hook
 - allow tool calls to proceed without secret/PII-based hook blocking
 - update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md` only for meaningful work turns
 - avoid automatic `wiki/queries/` and `wiki/decisions/` promotion in the default answer-first mode
@@ -100,6 +102,7 @@ The installed hooks:
 
 If you need to think about saving every answer manually, the setup has failed.
 If wiki maintenance delays the actual answer, the setup is being used wrong. The default capture mode is `LLM_WIKI_KIT_CAPTURE_MODE=answer-first`; the old eager query/decision capture path remains only as deprecated compatibility mode via `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager`.
+Pre-compact preservation always lets compaction proceed. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` suppresses failure warnings; `limited` and `soft` both emit a non-blocking warning if checkpoint storage fails. The hook reads only a bounded transcript tail controlled by `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`; the raw transcript path and authentication values are redacted before any checkpoint or recovery packet is written.
 
 ## Operational Commands
 
@@ -171,6 +174,7 @@ llm-wiki hook claude Stop
 ## Security Defaults
 
 - Full raw transcript capture is disabled by default.
+- PreCompact may read a small bounded transcript tail to create a redacted checkpoint, but it does not store the full transcript or raw `transcript_path`.
 - Tool calls are not blocked only because inputs look sensitive.
 - Authentication values such as tokens, passwords, and private keys are redacted before durable summaries are written.
 - Hook payloads are stored only as redacted event envelopes.

package/docs/integrations/claude-code.md

@@ -44,11 +44,12 @@ The hook records redacted turn summaries but does not deny tool calls only becau
 
 At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects functional compact context. The context still uses `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, relevant wiki/search state, operating rules, maintenance signals, passive runtime update status, and managed-template cleanup notes; the hook formats those signals so they are usable if shown in the Claude Code UI. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 
-`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` records a compaction note, and `PostCompact` records the note and returns fresh wiki context. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
+`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` classifies the current turn before compaction: simple turns record only a context note, meaningful work writes a live Q&A checkpoint, and durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event. `PostCompact` stores the redacted compact summary as a context note and prepares any pending recovery packet without returning model-visible context directly. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -33,7 +33,8 @@ Expected behavior:
 - `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
-- `PreCompact` records a compaction note; `PostCompact` records the note and returns fresh wiki context.
+- `PreCompact` classifies the current turn before compaction. Simple turns record only a context note; meaningful work writes a live Q&A checkpoint; durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event.
+- `PostCompact` stores the redacted compact summary as a context note and prepares any pending compact recovery packet. It does not return `hookSpecificOutput.additionalContext`, because Codex `PostCompact` only supports common output fields.
 - In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` appends live Q&A only for meaningful work turns and does not auto-create `wiki/queries/` or `wiki/decisions/`.
 - If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop` queues a pending maintenance item for agent review.
 - `Stop` clears the per-session turn buffer after recording. `SubagentStop` leaves the parent turn buffer available for the final stop event.
@@ -43,6 +44,7 @@ Hook payloads are stored as small redacted event envelopes rather than full tran
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 Run these after install:
 

package/docs/manual.md

@@ -62,7 +62,8 @@ llm-wiki/
 
 설치된 hook은 다음 일을 자동으로 수행한다.
 
-- session start, prompt submit, post compact 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status는 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
+- session start, instructions loaded, prompt submit 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status, compact recovery packet은 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
+- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, meaningful/durable turn은 redacted live Q&A checkpoint와 필요한 maintenance queue 후보를 남긴다. 저장 실패 시에도 compact는 진행시키고, 중요한 내용만 recovery packet으로 준비한다.
 - prompt/tool/result summary를 redaction한 뒤 turn buffer에 기록한다.
 - 의미 있는 작업 turn만 `outputs/questions/YYYY-MM-DD-live-qa.md`에 live Q&A로 남긴다.
 - 기본 answer-first mode에서는 `wiki/queries/`와 `wiki/decisions/`를 매 turn 자동 생성하지 않는다.
@@ -384,9 +385,11 @@ Claude Code handled events:
 - `Stop`
 - `SessionEnd`
 
-Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다.
+Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다. `PreCompact`는 checkpoint 생성을 위해 작은 bounded transcript tail만 읽을 수 있고, 저장 전 인증값과 raw `transcript_path`를 redaction한다.
 
-Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status를 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
+Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status, compact recovery packet을 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `PostCompact`는 compact summary 저장과 recovery packet 준비만 수행하고 model-visible context를 직접 반환하지 않는다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
+
+Pre-compact 보존은 compact를 block하지 않는다. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off`는 실패 warning을 억제하고, `limited`/`soft`는 checkpoint/queue 저장 실패 시 non-blocking warning만 남긴다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
 
 ## Security Defaults
 
@@ -396,6 +399,7 @@ Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는
 - token, password, bearer credential, private key, `.env` 원문 같은 authentication value는 durable summary에 쓰기 전 redaction한다.
 - phone number, email, date, business identifier는 local work context로 유용할 수 있어 기본 보존한다.
 - full raw transcript capture는 기본 기능이 아니다.
+- `PreCompact` checkpoint는 bounded redacted transcript tail만 사용할 수 있으며 full transcript와 raw `transcript_path`는 저장하지 않는다.
 - `llm-wiki lint`는 wiki 안의 secret-like content를 error로 보고한다.
 
 민감한 raw command output, log, screenshot, transcript를 저장해야 할 때는 먼저 redaction한다. 인증값은 wiki, report, live Q&A, command history에 남기지 않는다.

package/docs/operations.md

@@ -143,7 +143,9 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working
 
 Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject context automatically, but the current user answer takes priority over wiki cleanup. The active agent updates durable wiki pages when reusable project knowledge appears and the turn's importance or user consent justifies persistence. Hook context policy is function-first: memory, search, maintenance, and update signals remain available, while user-visible context is formatted as functional compact context instead of a raw dump.
 
-In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `PreCompact` performs the same answer-first classification before context compaction: simple turns get only a context note, archive-worthy turns get a live Q&A checkpoint, and durable candidates get a checkpoint plus queue item. If checkpoint storage fails, compaction still proceeds and the hook prepares an important-only compact recovery packet for the next legal context-injection event. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+
+Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`, but compaction is never blocked by llm-wiki-kit. `limited` and `soft` emit non-blocking failure warnings, and `off` suppresses failure output. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the small bounded transcript tail used for checkpoint context. Authentication values and the raw transcript path are redacted before storage.
 
 `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` keeps the old eager live Q&A/query/decision/maintenance behavior for compatibility only. New projects should rely on the answer-first default.
 

package/docs/security.md

@@ -13,4 +13,4 @@ Before writing durable summaries, the runtime redacts authentication values such
 
 Manual and hook context output also runs through redaction before returning excerpts or search hits. `llm-wiki lint` reports remaining secret-like wiki content as an error so it can be removed or rewritten before it becomes reusable project memory.
 
-Hook payloads are stored as small event envelopes, not full raw transcripts. Full transcript capture is intentionally not implemented as a default. If a project needs it, add a project-local policy and a redaction path first.
+Hook payloads are stored as small event envelopes, not full raw transcripts. Full transcript capture is intentionally not implemented as a default. `PreCompact` may read a small bounded transcript tail for a redacted checkpoint, but it does not store the raw transcript path or full transcript. If a project needs raw transcript capture, add a project-local policy and a redaction path first.

package/docs/troubleshooting.md

@@ -242,7 +242,7 @@ If the queue is always empty during ordinary Q&A, that is normal. If you expecte
 
 The hook does not block tool calls only because inputs look sensitive. Durable summaries redact authentication values before writing, while ordinary work context such as dates, phone numbers, emails, and business identifiers is preserved by default.
 
-Hook payloads are stored as small redacted event envelopes rather than full transcripts. Manual and hook context output is redacted before wiki excerpts or search hits are returned.
+Hook payloads are stored as small redacted event envelopes rather than full transcripts. `PreCompact` checkpoints may include a bounded redacted transcript tail, but the full transcript and raw `transcript_path` are not stored. Manual and hook context output is redacted before wiki excerpts or search hits are returned.
 
 ## Duplicate Pages Appear
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/compact-capture.js

@@ -0,0 +1,292 @@
+import { open, stat } from 'fs/promises';
+import { relative } from 'path';
+import { classifyTurn } from './capture-policy.js';
+import { recordMaintenanceForEntry } from './maintenance.js';
+import { appendContextNote, appendLiveQa, appendWikiLog } from './project.js';
+import { redactText, summarizeForStorage } from './redaction.js';
+import { buildEntryFromState, clearCompactRecovery, readCompactRecovery, writeCompactRecovery } from './state.js';
+
+const DEFAULT_PRECOMPACT_TAIL_BYTES = 32 * 1024;
+const MAX_PRECOMPACT_TAIL_BYTES = 256 * 1024;
+const ENFORCEMENT_MODES = new Set(['limited', 'soft', 'off']);
+
+export function preCompactEnforcementMode(env = process.env) {
+  const value = String(env.LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT || 'limited').toLowerCase();
+  return ENFORCEMENT_MODES.has(value) ? value : 'limited';
+}
+
+export function preCompactTranscriptTailBytes(env = process.env) {
+  const raw = env.LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES;
+  if (raw === undefined || raw === '') return DEFAULT_PRECOMPACT_TAIL_BYTES;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_PRECOMPACT_TAIL_BYTES;
+  return Math.min(Math.floor(parsed), MAX_PRECOMPACT_TAIL_BYTES);
+}
+
+export function compactSummaryText(payload) {
+  return summarizeForStorage(
+    payload.compact_summary ||
+      payload.compactSummary ||
+      payload.summary ||
+      payload.message ||
+      '',
+    4000
+  );
+}
+
+function transcriptPath(payload) {
+  return payload.transcript_path || payload.transcriptPath || '';
+}
+
+function redactTranscriptPath(text, path) {
+  let output = String(text || '');
+  if (path) output = output.split(path).join('[REDACTED:transcript-path]');
+  output = output.replace(/("transcript_path"\s*:\s*)"[^"]*"/gi, '$1"[REDACTED:transcript-path]"');
+  output = output.replace(/('transcript_path'\s*:\s*)'[^']*'/gi, "$1'[REDACTED:transcript-path]'");
+  output = output.replace(/\btranscript_path\s*=\s*[^\s"'`]+/gi, 'transcript_path=[REDACTED:transcript-path]');
+  return output;
+}
+
+async function readTranscriptTail(path, maxBytes) {
+  if (!path) return { ok: false, reason: 'missing-transcript-path', text: '' };
+  if (maxBytes <= 0) return { ok: false, reason: 'transcript-tail-disabled', text: '' };
+
+  let handle = null;
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return { ok: false, reason: 'transcript-not-file', text: '' };
+    const length = Math.min(info.size, maxBytes);
+    const start = Math.max(0, info.size - length);
+    const buffer = Buffer.alloc(length);
+    handle = await open(path, 'r');
+    await handle.read(buffer, 0, length, start);
+    const text = summarizeForStorage(redactTranscriptPath(buffer.toString('utf8'), path), 4000);
+    return {
+      ok: true,
+      text,
+      bytesRead: length,
+      truncated: info.size > maxBytes,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: summarizeForStorage(error?.code || error?.message || 'read-failed', 200),
+      text: '',
+    };
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function appendToField(current, addition) {
+  const existing = String(current || '').trim();
+  if (!existing || existing === '(not captured)') return addition;
+  return `${existing}\n${addition}`;
+}
+
+function entryWithTranscriptTail(entry, tail) {
+  const next = { ...entry };
+  if (tail.ok && tail.text) {
+    const marker = tail.truncated
+      ? 'PreCompact transcript tail (redacted bounded excerpt; earlier transcript omitted):'
+      : 'PreCompact transcript tail (redacted bounded excerpt):';
+    next.result = appendToField(next.result, `${marker}\n${tail.text}`);
+    next.followUp = appendToField(
+      next.followUp,
+      'Compact checkpoint includes only a bounded redacted transcript tail, not the raw transcript path or full transcript.'
+    );
+  } else if (tail.reason && tail.reason !== 'missing-transcript-path') {
+    next.followUp = appendToField(
+      next.followUp,
+      `Transcript tail unavailable during PreCompact (${tail.reason}); checkpoint used turn state only.`
+    );
+  }
+  return next;
+}
+
+function captured(value) {
+  const text = String(value || '').trim();
+  return text && text !== '(not captured)' ? text : '';
+}
+
+function sanitizeFailureText(projectRoot, value) {
+  let text = String(value || '');
+  if (projectRoot) text = text.split(projectRoot).join('[REDACTED:project-root]');
+  return summarizeForStorage(text, 1200);
+}
+
+function sanitizeFailures(projectRoot, failures) {
+  return failures.map((failure) => sanitizeFailureText(projectRoot, failure));
+}
+
+function formatRecoveryContext(recovery) {
+  const entry = recovery?.entry || {};
+  const lines = [
+    'LLM Wiki compact recovery:',
+    '- PreCompact preservation could not finish before compaction. Use this fallback context only for important lost details.',
+    `- classification: ${recovery?.classification || 'unknown'}`,
+  ];
+  if (recovery?.postCompactSummary) {
+    lines.push(`- compact summary: ${summarizeForStorage(recovery.postCompactSummary, 600)}`);
+  }
+  if (recovery?.failures) {
+    lines.push(`- preservation failure: ${summarizeForStorage(recovery.failures, 600)}`);
+  }
+  const fields = [
+    ['question', 'question', 900],
+    ['work', 'work', 1200],
+    ['result', 'result', 1400],
+    ['changedFiles', 'changed files', 700],
+    ['verification', 'verification', 700],
+    ['followUp', 'follow-up', 700],
+  ];
+  for (const [key, label, limit] of fields) {
+    const value = captured(entry[key]);
+    if (value) lines.push(`\n${label}:\n${summarizeForStorage(value, limit)}`);
+  }
+  return summarizeForStorage(lines.join('\n'), 5000);
+}
+
+async function recordCompactRecoveryFailure(projectRoot, payload, entry, classification, failures) {
+  const recovery = {
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    classification: classification.kind,
+    failures: summarizeForStorage(failures.join('; '), 1200),
+    entry: {
+      topic: summarizeForStorage(entry.topic, 300),
+      question: summarizeForStorage(entry.question, 1000),
+      work: summarizeForStorage(entry.work, 1600),
+      result: summarizeForStorage(entry.result, 1800),
+      changedFiles: summarizeForStorage(entry.changedFiles, 900),
+      verification: summarizeForStorage(entry.verification, 900),
+      followUp: summarizeForStorage(entry.followUp, 900),
+      firstTimestamp: entry.firstTimestamp,
+      session: entry.session,
+    },
+  };
+  recovery.context = formatRecoveryContext(recovery);
+  await writeCompactRecovery(projectRoot, payload, recovery);
+}
+
+function failureOutput(message, mode) {
+  if (mode === 'off') return {};
+  const reason = summarizeForStorage(message, 1200);
+  return {
+    systemMessage: `LLM Wiki PreCompact preservation warning: ${reason}`,
+  };
+}
+
+export async function handlePreCompactCapture(projectRoot, provider, eventName, payload) {
+  const mode = preCompactEnforcementMode();
+  const failures = [];
+  const tail = await readTranscriptTail(transcriptPath(payload), preCompactTranscriptTailBytes());
+  const stateEntry = await buildEntryFromState(projectRoot, payload, payload.last_assistant_message || payload.response || '');
+  const entry = entryWithTranscriptTail(stateEntry, tail);
+  const classification = classifyTurn(entry, eventName);
+
+  await appendContextNote(
+    projectRoot,
+    eventName,
+    [
+      `PreCompact classification: ${classification.kind}.`,
+      tail.ok ? `Transcript tail bytes read: ${tail.bytesRead}.` : `Transcript tail: ${tail.reason || 'not available'}.`,
+      'Turn state is intentionally kept for the later Stop/SessionEnd hook.',
+    ].join('\n')
+  ).catch((error) => {
+    failures.push(`context note failed: ${error?.message || error}`);
+  });
+
+  let liveQaPath = null;
+  if (classification.archive) {
+    const checkpointEntry = {
+      ...entry,
+      followUp: appendToField(
+        entry.followUp,
+        classification.suggestDurable
+          ? 'PreCompact saved this checkpoint and queued durable wiki review; merge reusable facts into existing wiki pages after the current answer.'
+          : 'PreCompact saved this checkpoint before context compaction; reusable facts should be merged only when appropriate.'
+      ),
+    };
+    try {
+      liveQaPath = await appendLiveQa(projectRoot, checkpointEntry);
+    } catch (error) {
+      failures.push(`live Q&A checkpoint failed: ${error?.message || error}`);
+    }
+  }
+
+  if (liveQaPath && ['suggest-durable', 'explicit-durable'].includes(classification.kind)) {
+    try {
+      const result = await recordMaintenanceForEntry(projectRoot, entry, {
+        source: liveQaPath,
+        eventName,
+        reason: 'PreCompact durable candidate checkpoint needs review after context compaction.',
+      });
+      if (result.created === false && result.reason) {
+        failures.push(`maintenance queue failed: ${result.reason}`);
+      }
+    } catch (error) {
+      failures.push(`maintenance queue failed: ${error?.message || error}`);
+    }
+  }
+
+  if (liveQaPath) {
+    await appendWikiLog(
+      projectRoot,
+      `precompact checkpoint; archive=${relative(projectRoot, liveQaPath)}; classification=${classification.kind}`
+    ).catch((error) => {
+      failures.push(`wiki log failed: ${error?.message || error}`);
+    });
+  }
+
+  if (failures.length > 0) {
+    let safeFailures = sanitizeFailures(projectRoot, failures);
+    if (classification.archive) {
+      try {
+        await recordCompactRecoveryFailure(projectRoot, payload, entry, classification, safeFailures);
+      } catch (error) {
+        failures.push(`compact recovery marker failed: ${error?.message || error}`);
+        safeFailures = sanitizeFailures(projectRoot, failures);
+      }
+    }
+    return failureOutput(`LLM Wiki PreCompact preservation did not complete. ${safeFailures.join('; ')}`, mode);
+  }
+
+  return {};
+}
+
+export async function recordPostCompactSummary(projectRoot, eventName, payload) {
+  const summary = compactSummaryText(payload);
+  await appendContextNote(
+    projectRoot,
+    eventName,
+    summary ? `Compact summary:\n${redactText(summary, 4000)}` : 'Compact summary was not provided.'
+  );
+}
+
+export async function finalizeCompactRecovery(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return null;
+  const summary = compactSummaryText(payload);
+  const next = {
+    ...recovery,
+    updated_at: new Date().toISOString(),
+    postCompactSummary: summary || recovery.postCompactSummary || '',
+    ready: true,
+  };
+  next.context = formatRecoveryContext(next);
+  await writeCompactRecovery(projectRoot, payload, next);
+  await appendContextNote(
+    projectRoot,
+    'PostCompact',
+    'Prepared compact recovery packet for the next legal model-visible hook context.'
+  ).catch(() => {});
+  return next;
+}
+
+export async function consumeCompactRecoveryContext(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return '';
+  await clearCompactRecovery(projectRoot, payload);
+  return recovery.context || formatRecoveryContext(recovery);
+}

package/src/hook.js

@@ -1,6 +1,7 @@
 import { findProjectRoot } from './fs-utils.js';
 import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
-import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { bootstrapProject, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { consumeCompactRecoveryContext, finalizeCompactRecovery, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
@@ -34,8 +35,16 @@ function toolSummary(payload) {
   return `${toolName}: ${summarizeForStorage(input, 1200)}`;
 }
 
-function contextOutput(eventName, context) {
+function supportsAdditionalContext(provider, eventName) {
+  const normalized = String(provider || '').toLowerCase();
+  if (normalized === 'codex') return ['SessionStart', 'UserPromptSubmit'].includes(eventName);
+  if (normalized === 'claude') return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+  return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+}
+
+function contextOutput(provider, eventName, context) {
   if (!context) return {};
+  if (!supportsAdditionalContext(provider, eventName)) return {};
   return {
     hookSpecificOutput: {
       hookEventName: eventName,
@@ -128,21 +137,30 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
-    const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, 'SessionStart'), payload);
-    return contextOutput(eventName, context);
+    const recovery = supportsAdditionalContext(provider, eventName)
+      ? await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '')
+      : '';
+    const context = await hookContext(
+      projectRoot,
+      eventName,
+      [recovery, await buildContextBrief(projectRoot, 'SessionStart')].filter(Boolean).join('\n\n'),
+      payload
+    );
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'UserPromptSubmit') {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
     const guidance = formatDurableCaptureGuidance(prompt);
+    const recovery = await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '');
     const context = await hookContext(
       projectRoot,
       eventName,
-      [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
+      [recovery, await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
       payload
     );
-    return contextOutput(eventName, context);
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'PreToolUse') {
@@ -156,11 +174,12 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'PreCompact' || eventName === 'PostCompact') {
-    await appendContextNote(projectRoot, eventName, 'Compaction lifecycle event captured by llm-wiki-kit.');
     if (eventName === 'PostCompact') {
-      return contextOutput(eventName, await buildContextBrief(projectRoot, eventName));
+      await recordPostCompactSummary(projectRoot, eventName, payload);
+      await finalizeCompactRecovery(projectRoot, payload).catch(() => {});
+      return {};
     }
-    return {};
+    return handlePreCompactCapture(projectRoot, provider, eventName, payload);
   }
 
   if (eventName === 'Stop' || eventName === 'SubagentStop' || eventName === 'SessionEnd') {

package/src/install.js

@@ -19,6 +19,8 @@ import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageRoot, runtimeVersion } from './version.js';
 
+const SESSION_START_MATCHER = 'startup|resume|clear|compact';
+
 export function hookCommand(provider, eventName, options = {}) {
   return commandForNodeScript(binPath, ['hook', provider, eventName], options);
 }
@@ -125,11 +127,23 @@ async function reconcileWindowsCommand() {
 
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
-  const already = hooks[eventName].some((entry) => (
+  const existing = hooks[eventName].find((entry) => (
     Array.isArray(entry?.hooks) &&
     entry.hooks.some((hook) => hook?.type === 'command' && hook?.command === command)
   ));
-  if (already) return false;
+  if (existing) {
+    let changed = false;
+    if (options.matcher && existing.matcher !== options.matcher) {
+      existing.matcher = options.matcher;
+      changed = true;
+    }
+    const hook = existing.hooks.find((item) => item?.type === 'command' && item?.command === command);
+    if (hook && options.commandWindows && hook.commandWindows !== options.commandWindows) {
+      hook.commandWindows = options.commandWindows;
+      changed = true;
+    }
+    return changed;
+  }
   const entry = {
     hooks: [
       {
@@ -186,12 +200,21 @@ function unsupportedKitClaudeEvents(hooks, supportedEvents) {
     .sort();
 }
 
-function hookTextIncludes(text, value) {
-  return normalizeHookPathText(text).includes(normalizeHookPathText(value));
+function expectedMatcher(eventName) {
+  return eventName === 'SessionStart' ? SESSION_START_MATCHER : undefined;
 }
 
-function hookEventIncludesBin(entries) {
-  return hookTextIncludes(JSON.stringify(entries || {}), binPath);
+function hookCommandMatches(hook, command) {
+  return hook?.command === command || hook?.commandWindows === command;
+}
+
+function hookEventIsCurrent(entries, eventName, command) {
+  const matcher = expectedMatcher(eventName);
+  return Array.isArray(entries) && entries.some((entry) => (
+    (!matcher || entry.matcher === matcher) &&
+    Array.isArray(entry?.hooks) &&
+    entry.hooks.some((hook) => hook?.type === 'command' && hookCommandMatches(hook, command))
+  ));
 }
 
 export async function install(options = {}) {
@@ -221,7 +244,7 @@ export async function install(options = {}) {
       changed.push('codex:replaced');
     }
     for (const eventName of CODEX_EVENTS) {
-      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      const matcher = expectedMatcher(eventName);
       const command = hookCommand('codex', eventName, { platform });
       const commandWindows = isWindows({ platform }) ? hookCommand('codex', eventName, { platform: 'win32' }) : undefined;
       if (addHook(codex.hooks, eventName, command, { matcher, commandWindows })) {
@@ -251,7 +274,7 @@ export async function install(options = {}) {
       changed.push(...removedUnsupported.map((eventName) => `claude:removed-unsupported:${eventName}`));
     }
     for (const eventName of claudeEvents) {
-      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      const matcher = expectedMatcher(eventName);
       if (addHook(claude.hooks, eventName, hookCommand('claude', eventName, { platform }), { matcher })) {
         claudeChanged = true;
         changed.push(`claude:${eventName}`);
@@ -312,9 +335,18 @@ export async function status(options = {}) {
   const claude = await readJson(claudeSettingsPath, {});
   const claudeDetection = detectClaudeVersion();
   const claudeEvents = supportedClaudeEvents(claudeDetection);
-  const claudeMissingEvents = claudeEvents.filter((eventName) => !hookEventIncludesBin(claude.hooks?.[eventName] || []));
+  const codexMissingEvents = CODEX_EVENTS.filter((eventName) => !hookEventIsCurrent(
+    codex.hooks?.[eventName] || [],
+    eventName,
+    hookCommand('codex', eventName, { platform })
+  ));
+  const claudeMissingEvents = claudeEvents.filter((eventName) => !hookEventIsCurrent(
+    claude.hooks?.[eventName] || [],
+    eventName,
+    hookCommand('claude', eventName, { platform })
+  ));
   const claudeUnsupportedKitEvents = unsupportedKitClaudeEvents(claude.hooks || {}, claudeEvents);
-  const codexInstalled = hookEventIncludesBin(codex.hooks || {});
+  const codexInstalled = codexMissingEvents.length === 0;
   const claudeInstalled = claudeMissingEvents.length === 0 && claudeUnsupportedKitEvents.length === 0;
   const discoveredCommandPaths = await findCommandPaths('llm-wiki', { platform });
   const commandPath = discoveredCommandPaths[0] || null;
@@ -344,6 +376,7 @@ export async function status(options = {}) {
     claudeVersion: claudeDetection.version || 'unknown',
     claudeModernHooks: claudeDetection.modern,
     claudeSupportedEvents: claudeEvents,
+    codexMissingEvents,
     claudeMissingEvents,
     claudeUnsupportedKitEvents,
     hooksCurrent: codexInstalled && claudeInstalled,

package/src/state.js

@@ -38,6 +38,22 @@ export async function clearTurnState(projectRoot, payload) {
   await unlink(statePath(projectRoot, payload)).catch(() => {});
 }
 
+export function compactRecoveryPath(projectRoot, payload) {
+  return join(kitDataDir(), 'compact-recovery', `${sessionKey(projectRoot, payload)}.json`);
+}
+
+export async function readCompactRecovery(projectRoot, payload) {
+  return readJson(compactRecoveryPath(projectRoot, payload), null);
+}
+
+export async function writeCompactRecovery(projectRoot, payload, recovery) {
+  await writeJson(compactRecoveryPath(projectRoot, payload), recovery);
+}
+
+export async function clearCompactRecovery(projectRoot, payload) {
+  await unlink(compactRecoveryPath(projectRoot, payload)).catch(() => {});
+}
+
 export async function rememberQuestion(projectRoot, payload, prompt) {
   const state = await readTurnState(projectRoot, payload);
   const clean = summarizeForStorage(prompt, 3000);