feat(miner-hands): add driver attempt log persistence and JSONL export (#4294)

[andriypolanski]

Closes #4294

Summary

• Extend packages/gittensory-engine/src/miner/attempt-log.ts with attempt_tool_edit in ATTEMPT_LOG_EVENT_TYPES and document miner-side persistence.
• Add packages/gittensory-miner/lib/attempt-log.js: append-only SQLite store keyed by attempt_id, importing normalizeAttemptLogEvent and formatAttemptLogJsonl from @jsonbored/gittensory-engine.
• Sibling store (not event-ledger extension): attempt events use a fixed driver lifecycle vocabulary and per-attempt JSONL export; event-ledger.js remains the general miner-loop audit trail (discovered_issue, plan_built, …) scoped by repo.
• Provide readAttemptLogEvents({ attemptId }) and exportAttemptLogJsonl(attemptId) for portable per-attempt traces.

Scope

• Pure event shapes + normalizeAttemptLogEvent in engine (incl. attempt_tool_edit)
• Monotonic seq + UNIQUE(seq) + BEGIN IMMEDIATE append path (mirrors event-ledger.js)
• JSON-round-trip payload rejection before insert
• Attempt-id scoping on read + JSONL export
• No UI changes — UI Evidence not required

Test plan

• packages/gittensory-engine/test/attempt-log.test.ts — vocabulary includes attempt_tool_edit
• test/unit/coding-agent-miner.test.ts — normalization vocabulary updated
• test/unit/miner-attempt-log.test.ts — path resolution, monotonic seq, attempt filter, JSONL export, payload rejection, append-only invariant
• npm run build:engine
• npm run build:miner
• npm run test:ci green
• npm audit --audit-level=moderate clean

Validation

git diff --check
npm run build:engine
npm run build:miner
npx vitest run test/unit/miner-attempt-log.test.ts test/unit/coding-agent-miner.test.ts
npm run test:ci
npm audit --audit-level=moderate

Changed files

File	Change
packages/gittensory-engine/src/miner/attempt-log.ts	Add attempt_tool_edit; document miner persistence
packages/gittensory-engine/test/attempt-log.test.ts	Vocabulary test update
packages/gittensory-miner/lib/attempt-log.js	New: SQLite persistence + JSONL export
packages/gittensory-miner/package.json	Syntax-check new module
packages/gittensory-miner/docs/coding-agent-driver.md	Link durable store
test/unit/coding-agent-miner.test.ts	Vocabulary test update
test/unit/miner-attempt-log.test.ts	New: miner store tests

API sketch

import {
  appendAttemptLogEvent,
  exportAttemptLogJsonl,
  initAttemptLog,
  readAttemptLogEvents,
} from "@jsonbored/gittensory-miner/lib/attempt-log.js";

const log = initAttemptLog();
log.appendAttemptLogEvent({
  eventType: "attempt_started",
  attemptId: "a-1",
  actionClass: "codegen",
  mode: "live",
  reason: "live run",
});
log.appendAttemptLogEvent({
  eventType: "attempt_tool_edit",
  attemptId: "a-1",
  actionClass: "codegen",
  mode: "live",
  reason: "edited src/foo.ts",
  payload: { path: "src/foo.ts" },
});
console.log(log.exportAttemptLogJsonl("a-1")); // portable JSONL trace

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.10%. Comparing base (3f23c61) to head (4f3c184).
⚠️ Report is 4 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4576   +/-   ##
=======================================
  Coverage   94.10%   94.10%           
=======================================
  Files         427      427           
  Lines       38022    38022           
  Branches    13877    13877           
=======================================
  Hits        35779    35779           
  Misses       1586     1586           
  Partials      657      657           

Files with missing lines	Coverage Δ
...ackages/gittensory-engine/src/miner/attempt-log.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-10 05:21:44 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a durable, append-only SQLite store for driver-level attempt events (packages/gittensory-miner/lib/attempt-log.js) plus a new attempt_tool_edit event type in the engine's fixed vocabulary, closing #4294. The implementation correctly mirrors the existing governor-ledger.js pattern (BEGIN IMMEDIATE + MAX(seq)+1 + UNIQUE(seq) for monotonic append, JSON round-trip validation before insert, corrupted-row detection on read), and the test suite in test/unit/miner-attempt-log.test.ts exercises path resolution, seq monotonicity, attempt-id scoping, JSONL export, and payload rejection against the real module rather than a fabricated stand-in. The PR is tightly scoped to the linked issue with no unrelated changes.

Nits — 5 non-blocking

• exportAttemptLogJsonl (attempt-log.js:143-147) reuses the engine's formatAttemptLogJsonl, which JSON.stringifies the row including a raw `payloadJson` string field rather than the parsed `payload` object, and drops `seq`/`createdAt`/`id` — worth a comment confirming that's the intended shape for a 'portable per-attempt trace' meant for external consumption.
• The append-only invariant test (test/unit/miner-attempt-log.test.ts, 'is append-only') only greps the module source for the literal words UPDATE/DELETE, which is a weak textual proxy — nothing at the SQL/schema level actually prevents an UPDATE against attempt_log_events, so the test only catches this module writing one, not a real DB-level guarantee.
• normalizeDbPath (attempt-log.js:23-25) calls resolveAttemptLogDbPath() to get the fallback default on every initAttemptLog() call even when an explicit dbPath is passed, doing redundant env resolution work.
• The PR's own test-plan checklist leaves `npm run build:engine`, `build:miner`, `test:ci`, and `npm audit` unchecked — worth confirming these were actually run before merge.
• Document (or change) whether the JSONL export is meant to carry parsed `payload` objects and `seq`/`createdAt` for audit purposes, since the current shape via formatAttemptLogJsonl double-encodes payload as a string and omits ordering/timestamp metadata.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4294
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 135 registered-repo PR(s), 84 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 135 PR(s), 25 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds the sibling SQLite persistence layer (packages/gittensory-miner/lib/attempt-log.js) mirroring governor-ledger.js's engine/miner pure-IO split with explicit rationale for not extending event-ledger.js, extends the engine's fixed ATTEMPT_LOG_EVENT_TYPES vocabulary with attempt_tool_edit, provides JSONL export via exportAttemptLogJsonl/formatAttemptLogJsonl, and includes tests covering mo

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Rust, Cuda, Kotlin, MDX, Scala
• Official Gittensor activity: 135 PR(s), 25 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.