@kenkaiiii/ggcoder 5.69.0 → 5.71.0

package/assets/skills/shared-language/SKILL.md

@@ -1,30 +1,32 @@
 ---
 name: shared-language
-description: Use when a project's domain vocabulary is fuzzy or drifting, naming decisions keep recurring, or a hard-to-reverse architectural decision needs recording so it is not re-litigated or re-suggested later. Do NOT use for throwaway scripts or projects too small to have recurring vocabulary.
+description: Use when a project's domain vocabulary is fuzzy or drifting (two names for one thing, one name for two), naming decisions keep recurring, or a hard-to-reverse architectural decision needs recording so it is not re-litigated or re-suggested — including mid-build when a term settles or a change contradicts an ADR. Do NOT use for throwaway scripts, projects too small to have recurring vocabulary, interviewing for requirements (clarify), or renames with no vocabulary decision (refactoring).
 ---
 
 # Shared Language
 
-A repo's terms are its compression. When you and the user mean the same thing by "reservation", every prompt, name, and doc gets shorter and sharper — and the agent stops spending thinking tokens re-deriving what a single word encodes. This skill builds and maintains that vocabulary.
+Two artifacts: the glossary (`CONTEXT.md`) and decision records (`docs/adr/`). On entry, read both if they exist, then act on the trigger: term settled → glossary; hard call made → offer ADR; change contradicts an ADR → surface it.
 
 ## The glossary — CONTEXT.md
 
-At the repo root. **A glossary and nothing else**: term — a one-to-three-line definition, no implementation details, no history. If a definition names a file path, it has become documentation; move that out.
+At the repo root. **A glossary and nothing else**: `term — 1–3 line definition`, plus `Avoid: <synonyms>` where drift exists. No file paths, implementation, or history.
 
-- Challenge fuzzy terms against it: "the glossary defines *cancellation* as pre-charge; this change reads as post-charge — which is meant?"
-- Stress-test a new term with an invented edge case before recording it ("is a no-show a cancellation?").
-- Update **inline, the moment a term settles** — never batch glossary edits for "later"; later never comes.
-- Name files, functions, variables, and tests with glossary terms verbatim. When code and glossary disagree, one of them is wrong — find out which.
-- Create the file lazily on the first settled term, never as an empty template.
-- On first creation, add one line to the repo's instruction file (AGENTS.md, or CLAUDE.md if that is what the repo uses): `Read CONTEXT.md before naming anything.` CONTEXT.md is not auto-loaded — the pointer is what makes the glossary ambient in every session.
+- Challenge fuzzy usage against it: "glossary says *cancellation* is pre-charge; this reads post-charge — which?"
+- Test a candidate term with an invented edge case before recording it ("is a no-show a cancellation?").
+- Update the moment a term settles; create the file lazily on the first settled term, never as an empty template.
+- Code, tests, and UI use glossary terms verbatim. Code and glossary disagree → one is wrong; ask which.
+- On creation, add to the repo's instruction file (AGENTS.md, or CLAUDE.md if that is what it uses): `Read CONTEXT.md before naming anything.` CONTEXT.md is not auto-loaded — that pointer is what makes it count in later sessions.
 
 ## Decision records — docs/adr/
 
-An ADR earns its file only when a decision is **hard to reverse**, **surprising without context**, and **a real tradeoff** — all three. One file per decision: title, 1–3 sentences of context, the decision, the main rejected alternative and why. Numbered; immutable once accepted — supersede, never edit.
+Only when a decision is **hard to reverse**, **surprising without context**, and **a real tradeoff** — all three. Offer it; don't write unasked.
 
-Read the ADRs before proposing a change that contradicts one: honor it, or surface the conflict to the user. Never silently relitigate a recorded decision, and never re-suggest a rejected alternative without new facts.
+- Follow the repo's existing ADR format. None? Use the MADR 4 minimal shape: `NNNN-title-with-dashes.md` with Context and Problem Statement, Considered Options, Decision Outcome (chosen option + why), Consequences; `status: accepted` in front matter.
+- Immutable once accepted — supersede, never edit: new ADR notes `Supersedes NNNN`; the old one's status becomes `superseded by NNNN` (the only allowed change).
+- Before proposing a change that contradicts an ADR: honour it or raise the conflict. Never re-suggest a rejected option without new facts.
 
-## Integration
+## Scaling: one agent or several
 
-- During a clarify session: settled terms go to the glossary; qualifying hard calls get an ADR offer.
-- Before naming anything: read the glossary if it exists.
+Main thread only. On a large repo, one `owl` may inventory competing terms across packages (occurrences with file:line); the main thread decides and edits.
+
+Sources (accessed 3 October 2026): MADR 4.0.0, latest release (2024-09-17) — https://adr.github.io/madr/; ubiquitous language — https://martinfowler.com/bliki/UbiquitousLanguage.html

package/assets/skills/tdd/SKILL.md

@@ -1,30 +1,42 @@
 ---
 name: tdd
-description: Use when the user asks for test-driven development, red-green-refactor, or "write the test first", or wants a feature built test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, or the change is throwaway probe code.
+description: Use when the user asks for test-driven development, red-green-refactor, "write the test first", or wants a feature or bug fix built test-first — including mid-build when they ask to switch to test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, the change is throwaway probe code, or the goal is restructuring without behaviour change (refactoring) or finding an unknown cause (root-cause).
 ---
 
 # TDD
 
-Red → green, one slice at a time. This skill is the reference that makes the loop produce tests worth keeping — most of it applies on every cycle, so consult it before and during the loop, not after.
+Red → green, one vertical slice at a time. Before the first test: agree seams (below). Then loop.
 
 ## Seams — agree before writing
 
-A **seam** is the public boundary where behavior is observable: an exported function, an HTTP route, a CLI invocation. Tests live at seams; they never reach into internals.
-
-Before the first test, write down the seams under test and confirm them with the user — which boundaries get tests and which stay untested is a decision, and settling it up front is what keeps effort on critical paths instead of every edge case. No test at an unagreed seam.
+A **seam** is a public boundary where behaviour is observable: exported function, HTTP route, CLI invocation. Tests live at seams, never in internals. List the seams under test and confirm them with the user (one `ask_user` call, recommended set marked). No test at an unagreed seam.
 
 ## The loop
 
-1. **Red.** One failing test at an agreed seam, for the next smallest real behavior. Run it; watch it fail for the right reason.
-2. **Green.** The least code that passes — nothing speculative. Run it.
-3. **Repeat.** The next test responds to what the last cycle taught. Work in vertical slices, never layers: writing all tests then all implementation verifies *imagined* behavior and locks in structure before understanding.
-4. **Refactor outside the loop.** Cleanup happens at a checkpoint after a green cycle or in a review pass — not interleaved guesswork inside red-green.
+1. **Red.** One failing test at an agreed seam for the next smallest real behaviour. Run it; confirm it fails for the right reason (assertion, not import/syntax error).
+2. **Green.** Least code that passes. Run the test and the touched suite.
+3. **Repeat.** The next test follows from what the last cycle taught. Never write all tests first, then all code.
+4. **Refactor** only on green, as a separate step; rerun tests after.
+
+## Test integrity (agent guard)
+
+- **Tests are frozen during green.** Never edit, delete, skip, loosen, or `.only` a test to make it pass. If a test is wrong, stop, say why, and get agreement before changing it.
+- Never special-case test inputs in production code (hard-coded returns for the test's literal).
+- Before claiming done, `git diff` the test files; explain any change made during a green step.
+
+## Test quality
+
+- **Expected values from an outside source of truth** — a known literal, worked example, or the spec. Never recompute the expected value the way the code does.
+- **Behaviour, not structure.** A test that breaks under a behaviour-preserving refactor is coupled to internals; rewrite it at the seam.
+- **Mock only external boundaries** (network, clock, filesystem), and only when slow or stateful.
+- **Name like a spec**: "user can check out with an empty cart".
+- **Property tests for rules over many inputs** (parsers, round-trips, invariants) when the project already has a property library (fast-check, Hypothesis, proptest); otherwise a table of examples.
+- **Optional strength check:** if a mutation tool is already installed (Stryker, mutmut, cargo-mutants), run it on the changed module; surviving mutants point to missing assertions. Do not install one unasked. Manual alternative: break one line of the new code, confirm a test goes red, revert.
+
+Never claim a cycle green that you did not run.
 
-## Test quality rules
+## Scaling: one agent or several
 
-- **Expected values from an outside source of truth** — a known literal, a worked example, the spec. Never recompute the expected value the same way the code does; that test can only agree with itself and can never catch the bug.
-- **Behavior, not structure.** Assert on what the interface does. A test that breaks under a refactor with unchanged behavior is coupled to implementation — rewrite it at the seam, never patch it with mocks of internals.
-- **Real paths over mocks.** Exercise real code; mock only external boundaries (network, clock, filesystem) and only when they are slow or stateful.
-- **Named like a spec.** "user can check out with an empty cart" — the name alone states the capability.
+Main thread only — the loop is sequential by design. Never parallelise red/green steps or let a child edit tests.
 
-The loop inherits the verification gate: never claim a cycle green that you did not run.
+Sources (accessed 3 October 2026): https://code.claude.com/docs/en/best-practices (failing test before the fix); https://stryker-mutator.io/docs/ (killed vs surviving mutants); https://hypothesis.readthedocs.io/

package/dist/app-sidecar.js

@@ -37,7 +37,7 @@ import { isWorkflowCommandText, countAssistantMessages, shouldStartAutopilotCycl
 import { driveAutopilotCycle, frameAutopilotInjection } from "./core/autopilot-cycle.js";
 import { describeRunVerification, describeTurnVerification } from "./core/run-status.js";
 import { validateKenModelPref, effectiveKenModel } from "./core/ken-model.js";
-import { normalizeAutopilotMarkersForHistory, normalizeAppMarkersForHistory, normalizeKenTurnsForHistory, getHistoryMessageVisibility, replayMessagesInOrder, restoreUserRow, restoreAssistantTexts, resolveRestoredCommand, autopilotMarkerCopySeed, } from "./core/session-history.js";
+import { normalizeAutopilotMarkersForHistory, normalizeAppMarkersForHistory, normalizeKenTurnsForHistory, getHistoryMessageVisibility, replayMessagesInOrder, restoreUserRow, restoreAssistantTexts, resolveRestoredCommand, autopilotMarkerCopySeed, extractToolImagePaths, } from "./core/session-history.js";
 import { sessionToMarkdown, defaultExportFilename, } from "./core/session-export.js";
 import { AuthStorage } from "./core/auth-storage.js";
 import { advancesPhase, explainPullFailure, isGgufShard, isValidHfRepoId, parseOllamaPullLine, pickGgufQuant, SHARDED_MESSAGE, toHfSearchRow, } from "./hf-pull.js";
@@ -72,7 +72,8 @@ import { installTerminationHandlers } from "./core/shutdown.js";
 import { KeepAwake } from "./core/keep-awake.js";
 import { RADIO_STATIONS, getCurrentStation, getRadioVolume, playRadio, setRadioVolume, stopRadio, } from "./core/radio.js";
 import { enrichProcessPath } from "./core/shell-path.js";
-import { downscaleForPreview, shrinkToFit, validateVisionImage } from "./utils/image.js";
+import { downscaleForPreview, IMAGE_MEDIA_TYPES, shrinkToFit, validateVisionImage, } from "./utils/image.js";
+import { readFileBounded } from "./tools/operations.js";
 import { startServeMode } from "./modes/serve-mode.js";
 import { installSteroids, probeSteroids } from "./core/steroids.js";
 import { loadTelegramConfig, saveTelegramConfig, verifyBotToken } from "./core/telegram-config.js";
@@ -996,6 +997,11 @@ async function main() {
     const shutdown = installTerminationHandlers({
         scope: "app-sidecar",
         teardown: async () => {
+            // Before any await: background commands live outside the daemon's process
+            // group, and the app force-kills that group after 3 s. If a slow session
+            // teardown is still pending then, these would never be stopped.
+            for (const c of sessions.values())
+                c.stopBackgroundProcesses();
             clearInterval(parentWatch);
             // Radio playback is app-wide (one stream across all windows), so it stops
             // at the daemon level, not per session.
@@ -1988,7 +1994,7 @@ async function createSession(deps, opts) {
     session.eventBus.on("hook", (d) => broadcast("hook", d));
     session.eventBus.on("diagnostics", (d) => broadcast("diagnostics", d));
     // Fires BEFORE the candidate final answer streams. The webview holds assistant
-    // text back while armed, so an Ideal review supersedes a draft that was never
+    // text back while armed, so an injected follow-up supersedes a draft that was never
     // painted instead of deleting one the user already started reading.
     session.eventBus.on("hook_armed", (d) => broadcast("hook_armed", d));
     session.eventBus.on("subagent_state", (d) => broadcast("subagent_state", d));
@@ -2060,10 +2066,8 @@ async function createSession(deps, opts) {
     // Autopilot (auto-review) toggle for THIS window's project. Loaded from
     // gg-app.json on boot; flipped via POST /autopilot. When on, POST /prompt runs
     // runAutopilotCycle after the user's turn settles — Ken auto-reviews the work
-    // and drives the review→prompt→review loop. Ken is the sole verification
-    // owner in this mode, so suppress the build session's redundant Ideal hook.
+    // and drives the review→prompt→review loop.
     let autopilot = mode === "code" && (await loadAutopilot(cwd));
-    session.setIdealReviewSuppressed(autopilot);
     // True while an autopilot review is in flight (used to defer kenAuto model
     // switches, like kenRunning does for chat Ken, and to drive the spinner).
     let autopilotReviewing = false;
@@ -2269,9 +2273,6 @@ async function createSession(deps, opts) {
             // (often >5 min) regardless of the user's global speedProfile pick.
             forceLongCacheRetention: true,
         });
-        // Ken is already the independent autopilot reviewer; recursively running
-        // his own Ideal self-review adds latency and can corrupt the verdict shape.
-        ken.setIdealReviewSuppressed(true);
         await ken.initialize();
         // Keep review text/tools silent; report usage only for whole-task accounting.
         ken.eventBus.on("turn_end", (d) => {
@@ -2536,7 +2537,6 @@ async function createSession(deps, opts) {
         const generation = runLifecycle.begin(abortOwnedWork).generation;
         pendingCancelDrain = null;
         autopilotActive = true;
-        session.setIdealReviewSuppressed(true);
         // Generation captured by the last plan review; acceptPlan re-checks it so
         // a user Accept/Reject landing mid-review always wins.
         let planGenAtReview = -1;
@@ -2654,7 +2654,6 @@ async function createSession(deps, opts) {
         }
         finally {
             autopilotActive = false;
-            session.setIdealReviewSuppressed(autopilot);
             finishOwnedGeneration(generation, true, session.getVerificationProblem() ? "unverified" : "completed");
             queueMicrotask(() => void runStrandedQueue());
         }
@@ -3289,7 +3288,16 @@ async function createSession(deps, opts) {
                 // Pre-index tool results by toolCallId so we can pair tool calls with
                 // their results (for sub-agent status + image extraction).
                 const toolResultMap = new Map();
+                // Tool name per call, so restore only trusts generate_image's own text
+                // when it reads extra images from disk (an MCP server could fake it).
+                const toolNameById = new Map();
                 for (const msg of messages) {
+                    if (msg.role === "assistant" && typeof msg.content !== "string") {
+                        for (const c of msg.content) {
+                            if (c.type === "tool_call")
+                                toolNameById.set(c.id, c.name);
+                        }
+                    }
                     if (msg.role !== "tool")
                         continue;
                     for (const tr of msg.content) {
@@ -3449,31 +3457,43 @@ async function createSession(deps, opts) {
                             const imageBlocks = tr.content.filter((c) => c.type === "image");
                             if (imageBlocks.length === 0)
                                 continue;
-                            // Extract the path from the text block (e.g. "Generated image → /path").
+                            // Extract the path from the text block so the restored image
+                            // stays clickable (read / screenshot / generate_image formats).
                             const textBlock = tr.content.find((c) => c.type === "text" && "text" in c && typeof c.text === "string");
                             const textContent = textBlock && textBlock.type === "text" ? textBlock.text : "";
-                            const pathMatch = textContent.match(/→\s*(\S+)/);
-                            const imgPath = pathMatch?.[1];
-                            // Downscale each image for the webview preview.
+                            const imgPaths = extractToolImagePaths(textContent);
+                            // Downscale each image for the webview preview. Paths pair with
+                            // image blocks in order (a tool saves one file per image).
                             const toolImages = [];
+                            let blockIndex = 0;
                             for (const block of imageBlocks) {
                                 if (block.type !== "image")
                                     continue;
-                                try {
-                                    const rawBuf = Buffer.from(block.data, "base64");
-                                    const previewBuf = await downscaleForPreview(rawBuf);
-                                    toolImages.push({
-                                        src: `data:${block.mediaType};base64,${previewBuf.toString("base64")}`,
-                                        path: imgPath,
-                                    });
-                                }
-                                catch {
-                                    // Downscale failed — use the raw data.
-                                    toolImages.push({
-                                        src: `data:${block.mediaType};base64,${block.data}`,
-                                        path: imgPath,
-                                    });
-                                }
+                                const imgPath = imgPaths[blockIndex++];
+                                const previewBuf = await downscaleForPreview(Buffer.from(block.data, "base64"));
+                                toolImages.push({
+                                    src: `data:${block.mediaType};base64,${previewBuf.toString("base64")}`,
+                                    path: imgPath,
+                                });
+                            }
+                            // generate_image persists only its first image's pixels; the
+                            // rest exist only on disk, so preview them from their files.
+                            // Skip silently if a file was moved or deleted since.
+                            const extraPaths = toolNameById.get(tr.toolCallId) === "generate_image"
+                                ? imgPaths.slice(blockIndex)
+                                : [];
+                            for (const extraPath of extraPaths) {
+                                const mediaType = IMAGE_MEDIA_TYPES[path.extname(extraPath).toLowerCase()];
+                                if (!mediaType)
+                                    continue;
+                                const raw = await readFileBounded(extraPath).catch(() => null);
+                                if (!raw)
+                                    continue;
+                                const previewBuf = await downscaleForPreview(raw);
+                                toolImages.push({
+                                    src: `data:${mediaType};base64,${previewBuf.toString("base64")}`,
+                                    path: extraPath,
+                                });
                             }
                             if (toolImages.length > 0) {
                                 history.push({
@@ -3904,9 +3924,6 @@ async function createSession(deps, opts) {
                     return;
                 }
                 autopilot = enabled;
-                // A toggle-off during an active cycle takes effect after Ken finishes;
-                // until then, injected build runs must not re-enable Ideal self-review.
-                session.setIdealReviewSuppressed(enabled || autopilotActive);
                 await saveAutopilot(cwd, enabled);
                 log("INFO", "app-sidecar", "autopilot toggled", { enabled: String(enabled) });
                 broadcast("autopilot", { autopilot: enabled });
@@ -5238,6 +5255,11 @@ async function createSession(deps, opts) {
         await kenAutoSession?.dispose().catch(() => { });
         await session.dispose().catch(() => { });
     }
+    function stopBackgroundProcesses() {
+        session.stopBackgroundProcesses();
+        kenSession?.stopBackgroundProcesses();
+        kenAutoSession?.stopBackgroundProcesses();
+    }
     return {
         id: opts.id,
         mode,
@@ -5251,6 +5273,7 @@ async function createSession(deps, opts) {
         broadcast,
         handle,
         dispose,
+        stopBackgroundProcesses,
     };
 }
 main().catch(async (err) => {