Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix: address self-review findings

Matt Van Horn40c8235d48db
diff --git a/commands/resume-session.md b/commands/resume-session.md
index c9bf3b726..dcc54d06c 100644
--- a/commands/resume-session.md
+++ b/commands/resume-session.md
@@ -30,8 +30,9 @@ This command is the counterpart to `/save-session`.
If no argument provided:
1. Check `~/.claude/session-data/`
-2. Pick the most recently modified `*-session.tmp` file
-3. If the folder does not exist or has no matching files, tell the user:
+2. Read the matching `*-session.tmp` candidates and apply the candidate ranking below
+3. Load the highest-ranked candidate
+4. If the folder does not exist or has no eligible matching files, tell the user:
```
No session files found in ~/.claude/session-data/
Run /save-session at the end of a session to create one.
@@ -42,11 +43,30 @@ If an argument is provided:
- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
`~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
- `YYYY-MM-DD-<shortid>-session.tmp` (current format)
- and load the most recently modified variant for that date
-- If it looks like a file path, read that file directly
+ `YYYY-MM-DD-<shortid>-session.tmp` (current format), apply the candidate ranking below across
+ all matches, and load the highest-ranked candidate for that date
+- If it looks like a file path, read exactly that file directly. Do not apply candidate ranking or
+ substitute a different file, even if the requested file is empty or another file is newer
- If not found, report clearly and stop
+#### Candidate ranking for implicit and date-based lookup
+
+Rank only automatically discovered candidates. Never use this ranking for an explicit file path.
+
+1. Reject files that are unreadable, empty, whitespace-only, or contain only headings, metadata,
+ separators, and placeholder values such as `[Session context goes here]`, `- [ ]`, a lone `-`,
+ or `[relevant files]`.
+2. Reject generated summaries with only one task and no populated files-modified, tools-used,
+ completed, in-progress, notes, or context-to-load content. This structural rule filters
+ one-message summarizer echoes without depending on any particular prompt text.
+3. Keep candidates with substantive populated content: completed work, in-progress work, concrete
+ next-session notes, concrete context paths, multiple tasks, modified files, or tools used.
+4. Among eligible substantive candidates, prefer the newest modification time.
+5. If modification times are equal, prefer more populated sections, then more non-placeholder
+ content, then larger byte size, then the lexicographically smaller resolved path. Count populated
+ sections and content only after removing headings, metadata, separators, and placeholder text.
+ These final tie-breaks make selection deterministic.
+
### Step 2: Read the entire session file
Read the complete file. Do not summarize yet.
@@ -96,7 +116,9 @@ If no next step is defined — ask the user where to start, and optionally sugge
## Edge Cases
**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
-Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
+Apply the candidate ranking across every matching legacy and current-format file. A substantive
+session must win over a newer placeholder or one-message summarizer echo; modification time decides
+between eligible candidates.
**Session file references files that no longer exist:**
Note this during the briefing — "WARNING: `path/to/file.ts` referenced in session but not found on disk."
@@ -108,7 +130,10 @@ Note the gap — "WARNING: This session is from N days ago (threshold: 7 days).
Read it and follow the same briefing process — the format is the same regardless of source.
**Session file is empty or malformed:**
-Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+For implicit or date-based discovery, reject it and continue ranking the remaining candidates. If no
+eligible candidate remains, report: "Session files were found but appear empty or unreadable. You may
+need to create a new one with /save-session." For an explicit path, report that the requested file is
+empty or unreadable without loading a substitute.
---
diff --git a/scripts/hooks/session-end.js b/scripts/hooks/session-end.js
index c224371aa..fcb94e84a 100644
--- a/scripts/hooks/session-end.js
+++ b/scripts/hooks/session-end.js
@@ -94,6 +94,10 @@ function extractSessionSummary(transcriptPath) {
};
}
+function isLowSubstanceTranscript(summary) {
+ return summary.totalMessages === 1 && summary.toolsUsed.length === 0 && summary.filesModified.length === 0;
+}
+
// Read hook input from stdin (Claude Code provides transcript_path via stdin JSON)
const MAX_STDIN = 1024 * 1024;
let stdinData = '';
@@ -181,6 +185,24 @@ async function main() {
}
}
+ // Classify known transcripts before resolving session metadata or touching the
+ // session directory. Missing, unreadable, or unparseable transcript data keeps
+ // the established fallback behavior because it cannot be classified reliably.
+ let summary = null;
+ let transcriptExists = false;
+ if (transcriptPath) {
+ transcriptExists = fs.existsSync(transcriptPath);
+ if (transcriptExists) {
+ summary = extractSessionSummary(transcriptPath);
+ if (summary && isLowSubstanceTranscript(summary)) {
+ log('[SessionEnd] Skipped one-message session without tool or file activity');
+ return;
+ }
+ } else {
+ log(`[SessionEnd] Transcript not found: ${transcriptPath}`);
+ }
+ }
+
const sessionsDir = getSessionsDir();
const today = getDateString();
// Derive shortId from transcript_path UUID when available, using the SAME
@@ -211,21 +233,10 @@ async function main() {
const currentTime = getTimeString();
- // Try to extract summary from transcript
- let summary = null;
-
- if (transcriptPath) {
- if (fs.existsSync(transcriptPath)) {
- summary = extractSessionSummary(transcriptPath);
- } else {
- log(`[SessionEnd] Transcript not found: ${transcriptPath}`);
- }
- }
-
// Decide whether to call LLM for a richer summary.
// Triggers: context remaining < 20%, or every 50 user messages as a baseline.
let llmSummary = null;
- if (transcriptPath && summary && fs.existsSync(transcriptPath)) {
+ if (transcriptPath && summary && transcriptExists) {
const contextPct = getContextRemainingPct(transcriptPath);
const isContextLow = contextPct !== null && contextPct < getContextThreshold();
const interval = parseInt(process.env.ECC_LLM_SUMMARY_INTERVAL || '50', 10);
diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.js
index 49d6f1e23..4c15970b0 100644
--- a/tests/hooks/hooks.test.js
+++ b/tests/hooks/hooks.test.js
@@ -4888,7 +4888,11 @@ async function runTests() {
const testDir = createTestDir();
const transcriptPath = path.join(testDir, 'transcript.jsonl');
// Only user messages — no tool_use entries at all
- const lines = ['{"type":"user","content":"How does authentication work?"}', '{"type":"assistant","message":{"content":[{"type":"text","text":"It uses JWT"}]}}'];
+ const lines = [
+ '{"type":"user","content":"How does authentication work?"}',
+ '{"type":"assistant","message":{"content":[{"type":"text","text":"It uses JWT"}]}}',
+ '{"type":"user","content":"Explain the token refresh path too"}'
+ ];
fs.writeFileSync(transcriptPath, lines.join('\n'));
const stdinJson = JSON.stringify({ transcript_path: transcriptPath });
@@ -5262,8 +5266,11 @@ async function runTests() {
await asyncTest('handles stdin exceeding MAX_STDIN (1MB) gracefully', async () => {
const testDir = createTestDir();
const transcriptPath = path.join(testDir, 'transcript.jsonl');
- // Create a minimal valid transcript so env var fallback works
- fs.writeFileSync(transcriptPath, JSON.stringify({ type: 'user', content: 'Overflow test' }) + '\n');
+ // Create a substantive valid transcript so env var fallback works
+ fs.writeFileSync(
+ transcriptPath,
+ [JSON.stringify({ type: 'user', content: 'Overflow test' }), JSON.stringify({ type: 'user', content: 'Verify fallback behavior' })].join('\n') + '\n'
+ );
// Create stdin > 1MB: truncated JSON will be invalid → falls back to env var
const oversizedPayload = '{"transcript_path":"' + 'x'.repeat(1048600) + '"}';
@@ -5880,6 +5887,8 @@ async function runTests() {
const lines = [
// Normal user message (string content) — should be included
'{"type":"user","content":"Real user message"}',
+ // A second valid message keeps this fixture eligible for persistence
+ '{"type":"user","content":"Follow-up user message"}',
// User message with numeric content — exercises the else: '' branch
'{"type":"user","content":42}',
// User message with boolean content — also hits the else branch
diff --git a/tests/hooks/session-end.test.js b/tests/hooks/session-end.test.js
index 9008674d9..c7eda47d8 100644
--- a/tests/hooks/session-end.test.js
+++ b/tests/hooks/session-end.test.js
@@ -37,6 +37,20 @@ function countOccurrences(haystack, needle) {
return n;
}
+function runHook(home, transcript, env = {}) {
+ return spawnSync('node', [script], {
+ encoding: 'utf8',
+ input: transcript ? JSON.stringify({ transcript_path: transcript }) : '',
+ env: { ...process.env, HOME: home, USERPROFILE: home, CLAUDE_SESSION_ID: '', ...env },
+ timeout: 10000,
+ });
+}
+
+function sessionFileFor(home, uuid) {
+ const shortId = sanitizeSessionId(uuid.slice(-8).toLowerCase());
+ return path.join(home, '.claude', 'session-data', `${getDateString()}-${shortId}-session.tmp`);
+}
+
function runTests() {
console.log('\n=== Testing session-end.js ===\n');
@@ -73,7 +87,10 @@ function runTests() {
const transcript = path.join(home, `${uuid}.jsonl`);
fs.writeFileSync(
transcript,
- JSON.stringify({ type: 'user', message: { role: 'user', content: userText } }) + '\n'
+ [
+ JSON.stringify({ type: 'user', message: { role: 'user', content: userText } }),
+ JSON.stringify({ type: 'tool_use', tool_name: 'Edit', tool_input: { file_path: '/src/release.js' } }),
+ ].join('\n') + '\n'
);
const res = spawnSync('node', [script], {
@@ -95,6 +112,132 @@ function runTests() {
}
}) ? passed++ : failed++);
+ (test('writes a session for a multi-message transcript', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const uuid = '11111111-2222-4333-8444-555555555555';
+ const transcript = path.join(home, `${uuid}.jsonl`);
+ fs.writeFileSync(
+ transcript,
+ [
+ JSON.stringify({ type: 'user', content: 'Investigate the failing hook' }),
+ JSON.stringify({ type: 'user', content: 'Add regression coverage' }),
+ ].join('\n') + '\n'
+ );
+
+ const res = runHook(home, transcript);
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+
+ const sessionFile = sessionFileFor(home, uuid);
+ const out = fs.readFileSync(sessionFile, 'utf8');
+ assert.ok(out.includes(START), 'Should include the generated summary start marker');
+ assert.ok(out.includes(END), 'Should include the generated summary end marker');
+ assert.ok(out.includes('**Last Updated:**'), 'Should include session metadata');
+ assert.ok(out.includes('Add regression coverage'), 'Should include the latest user task');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
+ (test('writes a session for one user message with tool activity', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const uuid = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee';
+ const transcript = path.join(home, `${uuid}.jsonl`);
+ fs.writeFileSync(
+ transcript,
+ [
+ JSON.stringify({ type: 'user', content: 'Fix the configuration' }),
+ JSON.stringify({ type: 'tool_use', tool_name: 'Edit', tool_input: { file_path: '/src/config.js' } }),
+ ].join('\n') + '\n'
+ );
+
+ const res = runHook(home, transcript);
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+ assert.ok(fs.existsSync(sessionFileFor(home, uuid)), 'Tool activity should make the session eligible');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
+ (test('skips a one-message prompt with no tool activity', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const uuid = '12345678-1234-4234-8234-123456789abc';
+ const transcript = path.join(home, `${uuid}.jsonl`);
+ fs.writeFileSync(transcript, JSON.stringify({ type: 'user', content: 'Print the current version' }) + '\n');
+
+ const res = runHook(home, transcript);
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+ assert.ok(!fs.existsSync(sessionFileFor(home, uuid)), 'One-shot prompt should not create a session file');
+ assert.ok(!fs.existsSync(path.join(home, '.claude', 'session-data')), 'Rejected transcript should not create the sessions directory');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
+ (test('skips a one-message summarizer-style transcript without prompt matching', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const uuid = 'fedcba98-7654-4321-8765-fedcba987654';
+ const transcript = path.join(home, `${uuid}.jsonl`);
+ fs.writeFileSync(
+ transcript,
+ [
+ JSON.stringify({ type: 'user', message: { role: 'user', content: 'Summarize the supplied conversation as concise markdown.' } }),
+ JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: '## Summary\nThe hook behavior was reviewed.' } }),
+ ].join('\n') + '\n'
+ );
+
+ const res = runHook(home, transcript);
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+ assert.ok(!fs.existsSync(sessionFileFor(home, uuid)), 'Summarizer subprocess should not create a session file');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
+ (test('does not rewrite an existing session for a rejected transcript', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const uuid = '99999999-8888-4777-8666-555555555555';
+ const transcript = path.join(home, `${uuid}.jsonl`);
+ const sessionFile = sessionFileFor(home, uuid);
+ const original = '# Session: preserved\n**Last Updated:** 09:00\n\n---\n\nUser-authored context\n';
+ const originalTime = new Date('2026-01-02T03:04:05.000Z');
+
+ fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+ fs.writeFileSync(sessionFile, original);
+ fs.utimesSync(sessionFile, originalTime, originalTime);
+ fs.writeFileSync(transcript, JSON.stringify({ type: 'user', content: 'Answer this one question' }) + '\n');
+
+ const res = runHook(home, transcript);
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+ assert.strictEqual(fs.readFileSync(sessionFile, 'utf8'), original, 'Rejected transcript should not change existing content');
+ assert.strictEqual(fs.statSync(sessionFile).mtimeMs, originalTime.getTime(), 'Rejected transcript should not advance mtime');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
+ (test('keeps fallback behavior when transcript metadata is malformed', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-end-'));
+ try {
+ const res = spawnSync('node', [script], {
+ encoding: 'utf8',
+ input: '{not-json',
+ env: { ...process.env, HOME: home, USERPROFILE: home, CLAUDE_SESSION_ID: 'fallback-session-12345678', CLAUDE_TRANSCRIPT_PATH: '' },
+ timeout: 10000,
+ });
+ assert.strictEqual(res.status || 0, 0, `hook exited ${res.status}: ${res.stderr}`);
+
+ const sessionsDir = path.join(home, '.claude', 'session-data');
+ assert.strictEqual(fs.readdirSync(sessionsDir).filter(name => name.endsWith('-session.tmp')).length, 1, 'Fallback should still create the placeholder session');
+ } finally {
+ fs.rmSync(home, { recursive: true, force: true });
+ }
+ }) ? passed++ : failed++);
+
console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
process.exit(failed > 0 ? 1 : 0);
}