@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/agent/hermes-parity-manifest.js

@@ -82,7 +82,8 @@ const FEATURES = [
             'npx tsx src/index.ts hermes doctor balanced --json',
             'npx tsx src/index.ts hermes portal status --json',
         ],
-        notes: 'Provider coverage is broad and buddy hermes providers status, buddy hermes doctor, plus Cowork now report active model source, inferred provider, detected env/OAuth credential sources without secret values, model capabilities, context/output limits, and Nous Portal readiness. Upstream provider setup wizards and Nous Portal OAuth are product decisions, not code gaps.',
+        notes: 'Provider coverage is broad and buddy hermes providers status, buddy hermes doctor, plus Cowork now report active model source, inferred provider, detected env/OAuth credential sources without secret values, model capabilities, context/output limits, and Nous Portal readiness. Upstream provider setup wizards and Nous Portal OAuth are product decisions, not code gaps. ' +
+            'DRIFT RE-AUDIT vs v2026.7.1 (2026-07-03): upstream added extra HTTP headers for LLM API calls (b98baa303) — FILLED same day: CODEBUDDY_LLM_EXTRA_HEADERS (JSON object) flows into the OpenAI-compat client as defaultHeaders, transport-managed headers dropped, proven with a REAL loopback HTTP round-trip (tests/codebuddy/providers/llm-extra-headers-real.test.ts). Upstream also added a Google Vertex AI provider with OAuth2 (c73e74386) — REGISTERED, not implemented: Code Buddy reaches Gemini via the native path/API key; the Vertex OAuth2 enterprise variant needs a GCP account for any honest validation, so writing it blind is refused (same rule as feishu pre-SDK).',
     },
     {
         id: 'toolsets',
@@ -167,7 +168,20 @@ const FEATURES = [
             'npx tsx src/index.ts hermes messaging gateway-status --json',
         ],
         notes: 'Channel coverage spans 26 adapter slots, but they are NOT uniform (honest breakdown 2026-06-13): ~11 have a real working persistent transport (discord, slack, telegram, whatsapp, signal, matrix, imessage BlueBubbles long-poll, plus irc/nostr/mattermost/nextcloud-talk — real TCP/WS/long-poll clients added 2026-06-14, ReconnectionManager-wired and loopback-mock-tested); ~a dozen are functional REST/webhook adapters that genuinely send over request/response with no socket to reconnect (e.g. dingtalk, qq, ntfy, line, zalo, twilio-voice, teams, google-chat, synology-chat, wecom, weixin, webchat); feishu real-time inbound is now wired to the OFFICIAL Lark SDK (@larksuiteoapi/node-sdk WSClient) via an optional runtime import (NOT a core dependency): when the SDK is installed and app creds are set, connect() starts the real long-connection and emits inbound messages (event parsing unit-tested); when the SDK is absent it degrades gracefully to the honest send-only state. REST outbound (tenant token -> im/v1/messages) works regardless. Gateway readiness is machine-readable through dedicated Hermes CLI status plus Cowork; send_message exists with dry-run outbox plus approval-gated live delivery; the exact discord tool covers upstream core REST actions; gateway lifecycle manager provides start/stop/restart/status per-channel and startAll/stopAll. ReconnectionManager (exponential backoff + jitter) was audited across all of them: the 6 original persistent adapters already had it, imessage is now wired (bespoke backoff replaced), and the new irc/nostr/mattermost transports are wired (reconnect proven against a loopback server dropping the connection). Reconnection is N/A for the REST/webhook class (no socket) and not-yet-applicable for the stub class (no real transport to drop) — documented per-adapter, not force-fitted. Slash-command parity: getRegisteredCommands() is implemented on the two adapters with a real command registry (discord, telegram); slack/matrix have no in-adapter registry so they are intentionally not fabricated. CLI: `buddy hermes messaging gateway-status --json`.',
-        nextWork: 'irc/nostr/mattermost/nextcloud-talk now have real, tested transports (2026-06-14). feishu inbound is now wired to the official Lark SDK (optional runtime import); live use needs `npm install @larksuiteoapi/node-sdk` + a real Feishu app + creds (an external-account gate, no longer a code stub). dingtalk/qq/ntfy are REST/webhook (no persistent socket — reconnection N/A). Live multi-platform delivery still needs ~20 platform tokens; Nostr publishing now works with a configured key (BIP-340 Schnorr signing added 2026-06-14 via @noble/curves, sign->verify round-trip tested).',
+        nextWork: 'irc/nostr/mattermost/nextcloud-talk now have real, tested transports (2026-06-14). feishu inbound is now wired to the official Lark SDK (optional runtime import); live use needs `npm install @larksuiteoapi/node-sdk` + a real Feishu app + creds (an external-account gate, no longer a code stub). dingtalk/qq/ntfy are REST/webhook (no persistent socket — reconnection N/A). Live multi-platform delivery still needs ~20 platform tokens; Nostr publishing now works with a configured key (BIP-340 Schnorr signing added 2026-06-14 via @noble/curves, sign->verify round-trip tested). ' +
+            'Telegram IS live-validated in production on this machine: the lisa-telegram systemd user service runs the Code Buddy Telegram channel 24/7 with a real bot token (companion chat + voice notes). ' +
+            'DRIFT RE-AUDIT vs v2026.7.1 (2026-07-03): per-channel model + system-prompt overrides (c43aa6301) are ' +
+            'now FILLED (same day) — resolution session > matched-route > bot-persona > route-default > global at the ' +
+            'single channel dispatch seam (channel-handlers.ts), a /model <name>|reset|show special command per ' +
+            'sessionKey, cached-agent reconciliation via setModel (history preserved), and the previously-DROPPED ' +
+            'RouteAgentConfig.systemPrompt now reaches the <runtime_persona> append. Proven by a pure resolver suite + 9 ' +
+            'tests through the real registerAIMessageHandler (src/channels/channel-model-override.ts). Slack Block Kit rendering (b080b93ad/7c7b48981) is now FILLED too ' +
+            '(2026-07-03): opt-in CODEBUDDY_SLACK_BLOCK_KIT renders agent markdown to blocks on send() — headers/dividers/' +
+            'code + markdown tables as NATIVE table blocks (schema verified against docs.slack.dev; oversized tables fall ' +
+            'back to a code section, text kept as the notification fallback), prose converted to Slack mrkdwn. Live ' +
+            'delivery remains account-gated (no Slack workspace in production here). Still registered, not covered: the ' +
+            'flat in-channel continuable cron delivery surface for Slack (4b4349eb9) — Slack-thread-specific; Code Buddy ' +
+            'reminders/cron already deliver to the production channel (Telegram).',
     },
     {
         id: 'browser-automation',
@@ -251,7 +265,7 @@ const FEATURES = [
             'npm test -- tests/memory tests/agent/lesson-candidate-queue.test.ts --run',
             'npx tsx src/index.ts user-model show --json',
         ],
-        notes: '6 of 8 official providers are adapted with real upstream contracts (paths/bodies from real plugins/SDKs): Mem0 (self-host REST + cloud), Honcho (v3), OpenViking (/api/v1), RetainDB (cloud), Supermemory (v3 cloud), ByteRover (brv CLI). All register and fall back to local until configured. `buddy hermes memory probe <id>` runs a live write->read round-trip (the discriminating test beyond shape tests); Cowork now exposes this same probe as a per-provider button in the Hermes memory strip. TWO providers are now LIVE-VALIDATED end-to-end on a self-hosted Ollama box (ministar): Honcho (async deriver) and Mem0. Validating Mem0 surfaced and fixed a real adapter bug: `remember` wrote to user_id `<id>:project` but `search`/`recall` read from bare `<id>`, so every project-scoped recall silently missed what was stored — shape tests passed regardless; only the live probe caught it (fix + regression test in network-memory-adapters[-real].ts). The 3 non-probeable adapters (Supermemory, RetainDB, OpenViking) were code-audited for the same partition-key asymmetry and are symmetric (write and read resolve to the same containerTag / project+user_id / tenant headers). Hindsight + Holographic are deliberately OUT of native-TS scope (in-process Python, no network/CLI boundary → parity-by-label). Self-host guide: docs/hermes-memory-providers-selfhost.md. Remaining unvalidated providers are dependency-gated (paid accounts / VLM models), not code gaps.',
+        notes: '6 of 8 official providers are adapted with real upstream contracts (paths/bodies from real plugins/SDKs): Mem0 (self-host REST + cloud), Honcho (v3), OpenViking (/api/v1), RetainDB (cloud), Supermemory (v3 cloud), ByteRover (brv CLI). All register and fall back to local until configured. `buddy hermes memory probe <id>` runs a live write->read round-trip (the discriminating test beyond shape tests); Cowork now exposes this same probe as a per-provider button in the Hermes memory strip. TWO providers are now LIVE-VALIDATED end-to-end on a self-hosted Ollama box (hub): Honcho (async deriver) and Mem0. Validating Mem0 surfaced and fixed a real adapter bug: `remember` wrote to user_id `<id>:project` but `search`/`recall` read from bare `<id>`, so every project-scoped recall silently missed what was stored — shape tests passed regardless; only the live probe caught it (fix + regression test in network-memory-adapters[-real].ts). The 3 non-probeable adapters (Supermemory, RetainDB, OpenViking) were code-audited for the same partition-key asymmetry and are symmetric (write and read resolve to the same containerTag / project+user_id / tenant headers). Hindsight + Holographic are deliberately OUT of native-TS scope (in-process Python, no network/CLI boundary → parity-by-label). Self-host guide: docs/hermes-memory-providers-selfhost.md. Remaining unvalidated providers are dependency-gated (paid accounts / VLM models), not code gaps.',
     },
     {
         id: 'skills',
@@ -320,7 +334,19 @@ const FEATURES = [
             'npm test -- tests/agent/learning-agent-real.test.ts --run',
             'npx tsx src/index.ts hermes learning status --json',
         ],
-        notes: 'Comparable direction with stricter review gates. Accepted user-model observations are injected per turn and counted by prompt-size diagnostics; reusable skill outcomes now keep scored recommendation history with reasons and next actions, and approved skill_manage mutations record rollback snapshot ids in Learning Agent telemetry. `buddy hermes learning status --json` now summarizes real local runs, trajectory event counts, retrospectives, lesson candidates, user-model observations, skill scoring, pattern library state, review gates, an aggregated review queue, and one prioritized next action without printing private model content. It chooses the next retrospective from the densest unfinished actionable trajectory and ignores low-signal memory-only runs that cannot produce lessons or skills. By default Honcho-style LLM inference and credential-free deterministic local inference both propose pending observations only (everything review-gated). Behavioural parity with Hermes\' direct background loop is now reachable via guarded opt-ins: accepted observations can auto-write through LocalUserModel.accept(), and interactive post-session background review can use the real headless tool registry for memory plus a deliberately narrowed skill_manage mutation surface. Autonomous review memories default to project scope; skill writes require CODEBUDDY_LEARNING_BACKGROUND_WRITE_SKILLS, block destructive/lifecycle actions, and append a rollback plan to the skill-write audit. OFF by default preserves the safe review-gated path byte-for-byte. Proven by round-trip tests plus a live headless-registry probe that writes project memory in a virgin workspace.',
+        notes: 'Comparable direction with stricter review gates. Accepted user-model observations are injected per turn and counted by prompt-size diagnostics; reusable skill outcomes now keep scored recommendation history with reasons and next actions, and approved skill_manage mutations record rollback snapshot ids in Learning Agent telemetry. `buddy hermes learning status --json` now summarizes real local runs, trajectory event counts, retrospectives, lesson candidates, user-model observations, skill scoring, pattern library state, review gates, an aggregated review queue, and one prioritized next action without printing private model content. It chooses the next retrospective from the densest unfinished actionable trajectory and ignores low-signal memory-only runs that cannot produce lessons or skills. By default Honcho-style LLM inference and credential-free deterministic local inference both propose pending observations only (everything review-gated). Behavioural parity with Hermes\' direct background loop is now reachable via guarded opt-ins: accepted observations can auto-write through LocalUserModel.accept(), and interactive post-session background review can use the real headless tool registry for memory plus a deliberately narrowed skill_manage mutation surface. Autonomous review memories default to project scope; skill writes require CODEBUDDY_LEARNING_BACKGROUND_WRITE_SKILLS, block destructive/lifecycle actions, and append a rollback plan to the skill-write audit. OFF by default preserves the safe review-gated path byte-for-byte. Proven by round-trip tests plus a live headless-registry probe that writes project memory in a virgin workspace. ' +
+            'DRIFT RE-AUDIT vs v2026.7.1 (2026-07-03): upstream\'s "journey" learned-node store gained full management — ' +
+            'list/edit/delete wired through CLI, RPC and REST plus TUI/desktop overlays (a0576560e/08be8e5ef/bb67dad07). ' +
+            'FILLED (same day) across the learned-knowledge stores: `buddy lessons show/rm/edit` (with a real ' +
+            'resurrection bug fixed — remove() rewrote only the project file, so global-only lessons came back; ' +
+            'origin-tracked per-file atomic rewrites now), /api/memory rewired from an ephemeral in-process Map onto the ' +
+            'REAL PersistentMemoryManager (key-as-id CRUD, non-reinforcing get() so REST reads don\'t distort the ' +
+            'forgetting curve), and `buddy research show/retract` on the CKG (append-only \'retraction\' tombstone, ' +
+            'revivable, replay-honored, backward-compatible with old readers). user-model already had full parity. All ' +
+            'proven with real files / real HTTP / real shared-ledger tests + live CLI round-trips. The REST leg is ' +
+            'complete too: /api/lessons (list/show/add/edit/delete on the same tracker primitives, scopes mirroring ' +
+            '/api/memory) — journey wires management through CLI, RPC and REST; Code Buddy now has CLI + REST, with ' +
+            'peer.tool.invoke as the fleet-RPC read surface.',
     },
     {
         id: 'cron-scheduling',
@@ -359,7 +385,8 @@ const FEATURES = [
             'npm test -- tests/fleet --run',
             'npm test -- tests/tools/execute-code-real.test.ts tests/tools/execute-code-tool-rpc.test.ts --run',
         ],
-        notes: 'Delegation is strong through Fleet and subagents, and execute_code now closes the upstream "scripts calling tools by RPC" surface: generated code can invoke Code Buddy tools over a file-framed runner<->subprocess RPC channel. Safe by construction — OFF by default (CODEBUDDY_EXECUTE_CODE_TOOL_RPC), allowlist + registry fleetSafe gate (read-only tools only) + per-run call bound + per-call timeout, and fail-closed (a clean structured denial when disabled, never a hang). Proven end-to-end: off-by-default refusal AND real on-flag round-trip (a tool-read result surfaces in the script stdout, js + python). The RPC allowlist can now be widened beyond read-only tools via CODEBUDDY_EXECUTE_CODE_RPC_TOOLS (comma-separated tool names) — these bypass the fleetSafe gate with explicit operator opt-in.',
+        notes: 'Delegation is strong through Fleet and subagents, and execute_code now closes the upstream "scripts calling tools by RPC" surface: generated code can invoke Code Buddy tools over a file-framed runner<->subprocess RPC channel. Safe by construction — OFF by default (CODEBUDDY_EXECUTE_CODE_TOOL_RPC), allowlist + registry fleetSafe gate (read-only tools only) + per-run call bound + per-call timeout, and fail-closed (a clean structured denial when disabled, never a hang). Proven end-to-end: off-by-default refusal AND real on-flag round-trip (a tool-read result surfaces in the script stdout, js + python). The RPC allowlist can now be widened beyond read-only tools via CODEBUDDY_EXECUTE_CODE_RPC_TOOLS (comma-separated tool names) — these bypass the fleetSafe gate with explicit operator opt-in. ' +
+            'DRIFT RE-AUDIT vs v2026.7.1 (2026-07-03): upstream grew an MoA (mixture-of-agents) advisory-fanout surface (per-preset fanout cadence 9e044cf79, reference_max_tokens 543d305bb, full-turn trace persistence 2e8748ed2). Code Buddy covers the advisory-fanout PATTERN with richer machinery — src/council/ (member output contract, dual-score judge, scoreboard ledger, deliberation-health JSONL) and buddy llm ensemble — but has no per-turn advisor cadence knob wired into the main chat loop; noted as an architecture difference (council is invoked, not ambient), not a missing capability.',
     },
     {
         id: 'runtime-backends',
@@ -518,7 +545,7 @@ const FEATURES = [
             'cowork/src/main/tools/hermes-claw-migrate-bridge.ts',
             'cowork/src/renderer/components/ClawMigrationDialog.tsx',
         ],
-        status: 'partial',
+        status: 'covered-partial',
         verificationCommands: [
             'npm test -- tests/agent/hermes-claw-migrate-real.test.ts tests/agent/hermes-claw-agent-settings.test.ts --run',
             'npx tsx src/index.ts hermes claw status --json',
@@ -547,11 +574,35 @@ const FEATURES = [
             'the gateway.auth.token archive was written 0644 and is now 0600 (all archive slices are now written 0600 unconditionally); nested ' +
             'secret names (gateway.auth.token, models.providers.*.apiKey) are now surfaced by name only. Regression-locked with ' +
             'sanitized real-shape fixtures. Remaining skips (memory/MCP/cron/...) are genuine source absences on this install, ' +
-            'not unverified readers.',
-        nextWork: 'Stays `partial`: MEMORY/MCP/cron readers are unexercised (this install has no such data), so the migrator full ' +
-            'reader set is not yet validated; flip to covered-partial only when a populated install exercises them. ' +
-            'identityBaseDirs intentionally ignores a workspace resolving outside the OpenClaw home (safety) — revisit if a ' +
-            'real out-of-tree workspace appears.',
+            'not unverified readers. ' +
+            'FLIPPED to `covered-partial` (2026-07-03): the last unexercised readers (MEMORY/MCP/cron) were finally exercised ' +
+            'against the live install after populating it THROUGH OpenClaw itself (`openclaw mcp set`, `openclaw cron add ' +
+            '--disabled`, plus MEMORY.md at the workspace root per OpenClaw\'s own AGENTS.md convention). Two real 2026.6.x ' +
+            'schema-drift bugs were found and fixed in the process: (1) MCP servers live under the nested `mcp.servers.<name>` ' +
+            'map, and the old root-key reader matched the bare `mcp` wrapper and imported ONE bogus server named "servers" ' +
+            '(clawMcpServers now resolves nested-then-legacy, wrapper never mis-read); (2) 2026.6.x cron jobs are persisted in ' +
+            'the gateway state DB (state/openclaw.sqlite:cron_jobs), never in openclaw.json — readClawStateCronJobs now reads ' +
+            'job_json read-only via better-sqlite3 (fail-soft null when absent/unavailable), mapClawStateCronJob maps the ' +
+            'verified job shape (5-field cron + agentTurn payload only) and the enabled flag is carried so a disabled OpenClaw ' +
+            'job is never silently activated after import. Full real round-trip proven: dry-run plan + --apply landed ' +
+            'mcpServers.filesystem, a disabled cronJobs entry, and the appended memory block in a throwaway target. ' +
+            'Regression-locked with sanitized real-shape fixtures (incl. a real-DDL sqlite fixture). ' +
+            'DRIFT RE-AUDIT (2026-07-03, same day): the local install was upgraded in place 2026.6.1 -> 2026.6.11 (npm ' +
+            'latest stable, ten versions) and everything re-validated LIVE: bridge validate-upstream 8/8 checks incl. ' +
+            'node.pair.list, migrator dry-run still 8 imports (memory/mcp/cron readers included — cron_jobs grew to 67 ' +
+            'columns but the reader only selects job_json, robust by construction), config top-level keys unchanged, and ' +
+            'the one upstream schema change in the range (stdio added to the MCP transport union, #95102) is pass-through ' +
+            'for the verbatim-merge MCP reader. Zero integration drift across ten upstream versions. ' +
+            'ADDENDUM (2026-07-03, same day): the legacy pre-sqlite `cron/jobs.json` file reader is now written too — ' +
+            'not blind: its shape ({version:1, jobs:[...]}, same job objects as the sqlite job_json) was verified against ' +
+            'OpenClaw\'s OWN migration reader (loadLegacyCronStoreForMigration/saveCronJobsStore in the installed 2026.6.1 ' +
+            'package\'s doctor-cron module). collectClawCronJobs now covers all three storage generations: config arrays ' +
+            '-> state DB (authoritative once populated) -> legacy file. Also: the live node.pair.list bridge check passes ' +
+            'now that the paired device holds operator.pairing (validate-upstream --apply: 8/8 checks).',
+        nextWork: 'Not `covered` because one long-tail reader stays honestly unverified for lack of source data anywhere: a ' +
+            'migratable memory-backend config (no such concept in the 2026.6.x openclaw.json — the memory_backend skip is ' +
+            'correct, legacy-clawdbot-only, fixture-tested but never seen on a real install). identityBaseDirs intentionally ' +
+            'ignores a workspace resolving outside the OpenClaw home (safety) — revisit if a real out-of-tree workspace appears.',
     },
 ];
 export function buildHermesParityManifest(generatedAt = new Date().toISOString()) {
@@ -575,9 +626,12 @@ export function buildHermesParityManifest(generatedAt = new Date().toISOString()
         officialSource: {
             repository: 'https://github.com/NousResearch/hermes-agent',
             docs: 'https://hermes-agent.nousresearch.com/docs/',
-            inspectedCommit: '5921d667',
-            latestTagObserved: 'v2026.5.29.2',
-            auditDocument: 'docs/hermes-agent-official-parity-audit-2026-05-30.md',
+            // Drift re-audit 2026-07-03: origin/main fetched from the local
+            // ~/hermes-agent checkout; new-surface deltas registered per-entry
+            // (see notes dated 2026-07-03). Prior anchor: 5921d667 / v2026.5.29.2.
+            inspectedCommit: '1c4cc00f7',
+            latestTagObserved: 'v2026.7.1',
+            auditDocument: 'docs/hermes-openclaw-parity.md',
         },
         summary,
         features: FEATURES.map((feature) => ({ ...feature })),
@@ -643,7 +697,7 @@ export function buildHermesParityTodo(options = {}) {
         deferred,
         notes: [
             'Derived from the same official Hermes feature parity manifest as `buddy hermes parity --json`.',
-            'OpenClaw migration is deferred for full-parity completion (an initial `claw migrate` is implemented); the deferred remainder is appended only after active work when --include-deferred is passed.',
+            'Covered-partial items retain their evidence and honest long-tail limitations in the parity manifest, but are not active implementation gaps.',
             'Each todo keeps one real verification command so the next agent can prove progress without relying on mocks.',
         ],
     };

package/dist/agent/infrastructure/agent-infrastructure.d.ts

@@ -224,4 +224,5 @@ export declare function createAgentInfrastructureSync(options: {
     model: string;
     baseURL?: string;
     maxContextTokens?: number;
+    workingDirectory?: string;
 }, config?: AgentInfrastructureConfig): AgentInfrastructure;

package/dist/agent/infrastructure/agent-infrastructure.js

@@ -436,7 +436,7 @@ export function createAgentInfrastructureSync(options, config = {}) {
     const deps = {
         container,
         tokenCounter: createTokenCounter(options.model),
-        contextManager: createContextManager(options.model, options.maxContextTokens),
+        contextManager: createContextManager(options.model, options.maxContextTokens, options.workingDirectory),
         modeManager: getAgentModeManager(),
         sandboxManager: getSandboxManager(),
         mcpClient: getMCPClient(),

package/dist/agent/isolation/agent-workspace.js

@@ -11,6 +11,7 @@ import fs from 'fs-extra';
 import * as crypto from 'crypto';
 import { generateSessionKey } from './agent-config.js';
 import { logger } from '../../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../../utils/atomic-write.js';
 /**
  * Default workspace configuration
  */
@@ -181,7 +182,7 @@ export class AgentWorkspace extends EventEmitter {
                 state: this.state.state,
             },
         };
-        await fs.writeJSON(stateFile, data, { spaces: 2 });
+        await writeJsonAtomic(stateFile, data, { mode: 0o600 });
     }
     /**
      * Load workspace state from disk
@@ -192,7 +193,9 @@ export class AgentWorkspace extends EventEmitter {
             return false;
         }
         try {
-            const data = await fs.readJSON(stateFile);
+            const data = await readJsonAtomic(stateFile, null);
+            if (!data?.session || !data.state)
+                return false;
             this.session = data.session;
             this.state = {
                 workingDirectory: data.state.workingDirectory || process.cwd(),

package/dist/agent/learning/skill-background-writes.js

@@ -24,6 +24,7 @@
 import fs from 'fs';
 import path from 'path';
 import { logger } from '../../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../../utils/atomic-write.js';
 import { getBackgroundWritePolicy } from '../learning-background-writes.js';
 import { OMISSION_RE, SECRET_RE } from '../self-improvement/empirical-gate.js';
 import { installResearchScriptSkillCandidate, } from '../research-script-skill-candidate.js';
@@ -201,7 +202,7 @@ function recordSkillWriteAudit(workDir, entry) {
     file.entries.push(entry);
     try {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`, 'utf-8');
+        writeJsonAtomicSync(filePath, file, { mode: 0o600 });
     }
     catch (err) {
         logger.warn('[skill-background-writes] failed to persist audit entry', {
@@ -211,10 +212,14 @@ function recordSkillWriteAudit(workDir, entry) {
 }
 function readAuditFile(filePath) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-        if (parsed.schemaVersion === SKILL_WRITE_AUDIT_SCHEMA_VERSION && Array.isArray(parsed.entries)) {
+        const parsed = readJsonAtomicSync(filePath, null, {
+            mode: 0o600,
+            isValid: (value) => Boolean(value && typeof value === 'object' &&
+                value.schemaVersion === SKILL_WRITE_AUDIT_SCHEMA_VERSION &&
+                Array.isArray(value.entries)),
+        });
+        if (parsed)
             return parsed;
-        }
     }
     catch {
         // Fall through to a fresh file.

package/dist/agent/learning-agent.js

@@ -13,6 +13,7 @@ import { buildRunTrajectoryExport, } from '../observability/run-trajectory-expor
 import { getLessonCandidateQueue } from './lesson-candidate-queue.js';
 import { parseSkillFile, validateSkill } from '../skills/parser.js';
 import { logger } from '../utils/logger.js';
+import { writeFileAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
 export const LEARNING_RETROSPECTIVE_SCHEMA_VERSION = 1;
 export const LEARNING_PATTERN_LIBRARY_SCHEMA_VERSION = 1;
 export const LEARNING_SKILL_USAGE_SCHEMA_VERSION = 1;
@@ -650,8 +651,8 @@ function materializeLearningSkillCandidates(retrospective, workDir) {
             };
             fs.mkdirSync(path.dirname(absoluteSkillPath), { recursive: true });
             fs.mkdirSync(path.dirname(absoluteReviewPath), { recursive: true });
-            fs.writeFileSync(absoluteSkillPath, `${skillMarkdown.trimEnd()}\n`, 'utf-8');
-            fs.writeFileSync(absoluteReviewPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+            writeFileAtomicSync(absoluteSkillPath, `${skillMarkdown.trimEnd()}\n`, { mode: 0o600 });
+            writeJsonAtomicSync(absoluteReviewPath, manifest, { mode: 0o600 });
             materialized.push(reviewedCandidate);
         }
         catch (error) {
@@ -904,8 +905,7 @@ function normalizeLearningSkillUsageRecord(record) {
     };
 }
 function writeJsonFile(filePath, value) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+    writeJsonAtomicSync(filePath, value, { mode: 0o600 });
 }
 function patternKey(sequence) {
     return createHash('sha256').update(sequence.join('\0')).digest('hex').slice(0, 16);

package/dist/agent/learning-background-writes.js

@@ -32,6 +32,7 @@
 import fs from 'fs';
 import path from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
 /** Reviewer sentinel stamped on every background auto-write. */
 export const BACKGROUND_WRITE_REVIEWER = 'auto:background-write';
 export const BACKGROUND_WRITE_AUDIT_SCHEMA_VERSION = 1;
@@ -140,7 +141,7 @@ function recordBackgroundWriteAudit(workDir, entry) {
     file.entries.push(entry);
     try {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`, 'utf-8');
+        writeJsonAtomicSync(filePath, file, { mode: 0o600 });
     }
     catch (err) {
         logger.warn('[learning-background-writes] failed to persist audit entry', {
@@ -150,11 +151,14 @@ function recordBackgroundWriteAudit(workDir, entry) {
 }
 function readAuditFile(filePath) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-        if (parsed.schemaVersion === BACKGROUND_WRITE_AUDIT_SCHEMA_VERSION &&
-            Array.isArray(parsed.entries)) {
+        const parsed = readJsonAtomicSync(filePath, null, {
+            mode: 0o600,
+            isValid: (value) => Boolean(value && typeof value === 'object' &&
+                value.schemaVersion === BACKGROUND_WRITE_AUDIT_SCHEMA_VERSION &&
+                Array.isArray(value.entries)),
+        });
+        if (parsed)
             return parsed;
-        }
     }
     catch {
         // Fall through to a fresh file.

package/dist/agent/lesson-candidate-queue.d.ts

@@ -30,6 +30,10 @@ export interface LessonCandidateProvenance {
     sagaId?: string;
     /** Free-form note, e.g. "proposed after passing verification on task X". */
     note?: string;
+    /** Deterministic triage score (0..1) from council-lesson-proposer — helps the human sort the queue. */
+    pedagogicalValue?: number;
+    /** The score's component factors (substance, resolution, testability, generalizability, stanceDivergence). */
+    valueFactors?: Record<string, number>;
 }
 export interface LessonCandidate {
     id: string;

package/dist/agent/lesson-candidate-queue.js

@@ -24,6 +24,7 @@
 import fs from 'fs';
 import path from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
 import { getLessonsTracker } from './lessons-tracker.js';
 export const LESSON_CANDIDATE_SCHEMA_VERSION = 1;
 const VALID_CATEGORIES = ['PATTERN', 'RULE', 'CONTEXT', 'INSIGHT'];
@@ -195,9 +196,14 @@ export class LessonCandidateQueue {
             return;
         this.loaded = true;
         try {
-            if (!fs.existsSync(this.filePath))
+            const parsed = readJsonAtomicSync(this.filePath, null, {
+                mode: 0o600,
+                isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value) &&
+                    value.schemaVersion === LESSON_CANDIDATE_SCHEMA_VERSION &&
+                    Array.isArray(value.candidates)),
+            });
+            if (!parsed)
                 return;
-            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
             if (Array.isArray(parsed.candidates)) {
                 this.candidates = parsed.candidates.filter(isValidCandidate);
             }
@@ -215,7 +221,7 @@ export class LessonCandidateQueue {
                 schemaVersion: LESSON_CANDIDATE_SCHEMA_VERSION,
                 candidates: this.candidates,
             };
-            fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+            writeJsonAtomicSync(this.filePath, file, { mode: 0o600 });
         }
         catch (err) {
             logger.warn('[lesson-candidates] failed to save queue', {

package/dist/agent/lesson-provenance.js

@@ -18,6 +18,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
 const MAX_USAGE_PER_LESSON = 200;
 export class LessonProvenanceIndex {
     filePath;
@@ -96,9 +97,14 @@ export class LessonProvenanceIndex {
             return;
         this.loaded = true;
         try {
-            if (!fs.existsSync(this.filePath))
+            const parsed = readJsonAtomicSync(this.filePath, null, {
+                mode: 0o600,
+                isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value) &&
+                    value.schemaVersion === 1 &&
+                    typeof value.records === 'object'),
+            });
+            if (!parsed)
                 return;
-            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
             for (const [id, record] of Object.entries(parsed.records ?? {})) {
                 this.records.set(id, { ...record, lessonId: id, usedBy: record.usedBy ?? [] });
             }
@@ -114,7 +120,7 @@ export class LessonProvenanceIndex {
                 schemaVersion: 1,
                 records: Object.fromEntries(this.records),
             };
-            fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+            writeJsonAtomicSync(this.filePath, file, { mode: 0o600 });
         }
         catch (err) {
             logger.debug('LessonProvenanceIndex: failed to save index', { error: String(err) });

package/dist/agent/lessons-tracker.d.ts

@@ -24,6 +24,27 @@ export interface LessonItem {
     createdAt: number;
     source: 'user_correction' | 'self_observed' | 'manual';
 }
+/** Which lessons.md file a lesson lives in. */
+export type LessonScope = 'project' | 'global';
+export interface LessonLocation {
+    scope: LessonScope;
+    path: string;
+}
+/** Patch for `update()` — `context: null` clears the context. */
+export interface LessonPatch {
+    content?: string;
+    category?: LessonCategory;
+    context?: string | null;
+}
+/** Options for the per-turn lessons context block. */
+export interface LessonsContextOptions {
+    /** Rank lessons against this text (BM25) within each category; default = recency. */
+    query?: string;
+    /** Character budget for the lesson lines (default 2000). */
+    maxChars?: number;
+}
+/** Default per-turn character budget for `<lessons_context>`. */
+export declare const DEFAULT_LESSONS_CONTEXT_CHARS = 2000;
 export type LessonConceptSource = 'context' | 'wiki_link' | 'markdown_link' | 'tag' | 'related' | 'keyword';
 export type LessonGraphRenderFormat = 'summary' | 'json' | 'markdown' | 'mermaid';
 export interface LessonConceptRef {
@@ -124,8 +145,11 @@ export declare class LessonsTracker {
     private projectPath;
     private globalPath;
     private items;
+    /** Which file(s) each lesson id was loaded from (see load()). */
+    private locationsById;
     private loaded;
     private _cachedBlock;
+    private _cachedKey;
     private _cacheTime;
     /**
      * Serialized write chain (F33).
@@ -165,7 +189,40 @@ export declare class LessonsTracker {
         sagaId?: string;
         note?: string;
     }): LessonItem;
+    /**
+     * Delete a lesson (fire-and-forget). Rewrites every file the id lives in —
+     * the previous implementation rewrote only the PROJECT file, so removing a
+     * lesson that lived only in `~/.codebuddy/lessons.md` resurrected it on the
+     * next fresh load. Use `removeWithReport()` to await the writes and learn
+     * which file(s) were touched.
+     */
     remove(id: string): boolean;
+    /** Look up one lesson by id, with the file location(s) it lives in. */
+    get(id: string): (LessonItem & {
+        locations: LessonLocation[];
+    }) | undefined;
+    /**
+     * Edit a lesson in place. `id`, `createdAt` and `source` are preserved (the
+     * metadata comment is regenerated from them); a category change regroups the
+     * line under the new `## CATEGORY` heading at serialisation. Every file the
+     * id lives in is rewritten atomically. Throws on a patch that would corrupt
+     * the markdown line format.
+     */
+    update(id: string, patch: LessonPatch): Promise<(LessonItem & {
+        locations: LessonLocation[];
+    }) | undefined>;
+    /** Delete a lesson from every file it lives in, reporting which ones. */
+    removeWithReport(id: string): Promise<{
+        removed: boolean;
+        removedFrom: LessonLocation[];
+    }>;
+    private locationsOf;
+    /**
+     * Atomically rewrite ONE lessons file through the serialized write queue:
+     * the file is re-read fresh inside the queue (so a concurrent writer's
+     * changes are preserved), mutated, written to `<file>.tmp` and renamed over.
+     */
+    private rewriteLessonsFile;
     clearByCategory(category?: LessonCategory): number;
     list(category?: LessonCategory): LessonItem[];
     search(query: string, category?: LessonCategory): LessonItem[];
@@ -198,12 +255,22 @@ export declare class LessonsTracker {
     /**
      * Build the per-turn context block injected BEFORE the todo suffix.
      * Returns null when there are no lessons (avoids noisy injections).
+     *
+     * BUDGETED: the block used to emit EVERY active lesson on EVERY turn (and
+     * again on every round) — an unbounded per-turn token tax that grows as
+     * lessons accumulate. It now packs a character budget in priority order:
+     * category first (RULE is contractual and always outranks INSIGHT), then
+     * BM25 relevance to the current message when provided, else recency.
+     * Packing stops at the first overflow so a low-priority lesson can never
+     * displace a higher-priority one, and the dropped count is stated honestly
+     * instead of silently truncating.
      */
-    buildContextBlock(): string | null;
+    buildContextBlock(options?: LessonsContextOptions): string | null;
     getStats(): LessonsStats;
     export(format?: 'json' | 'md' | 'csv'): string;
     autoDecay(maxAgeDays?: number): number;
     private serialise;
+    private serialiseItems;
     private loadFile;
     private parseMd;
 }