jeo-code 0.7.16 → 0.7.17

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
 
+## [0.7.17] - 2026-06-25
+_Developer workflow parity (gjc `dev:link`/`dev:doctor`, adapted for jeo's zero-native-dep Bun runtime): the global `jeo` command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when `jeo` resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact._
+
+### Added
+- **`bun run dev:link` / `dev:doctor` run the global `jeo` from this checkout's source.** New `scripts/dev-link.ts`: `link` symlinks `jeo` → `<repo>/src/cli.ts` into `~/.local/bin` (override `JEO_DEV_LINK_DIR`), refuses to proceed when another `jeo` shadows the managed link earlier on `PATH`, ensures the `#!/usr/bin/env bun` entry stays executable, and runs a `--version` smoke test; `doctor` classifies whatever `jeo` the current `PATH` resolves to as `linked` (this hot source), `drift` (a compiled binary or npm-installed copy — exit 1), or `missing`. Unlike gjc there is no `build:native` prerequisite — jeo has zero native deps, so a bare symlink to the shebang entry is fully functional. Pure helpers (`findShadowingJeo`, `classifyDevDoctor`, `splitPathEntries`, `defaultLinkDir`, `resolveJeoOnPath`) back the `dev:link`/`dev:doctor` `package.json` scripts.
+- **OKF concept memory gains in-memory search, scoring, and budget-aware injection.** `src/agent/memory.ts` adds `loadConcepts`/`scoreConcept`/`searchConcepts` over the OKF concept bundle (`.jeo/memory`), `index.md` progressive disclosure, and a relevance-selected `memoryPromptSection` that fills the `MEMORY_INJECT_MAX_CHARS` budget by picking whole high-scoring concepts instead of mid-string truncation, plus `recordFailedAttempt` for failure-aware recall (docs/okf_mem sprint-03 Search & Reference).
+
+### Changed
+- **README documents skill migration/inspection and the dev workflow.** New "Skill migration and bundled skill inspection" section walks `jeo skills list` / `read <name>` / `sync --check` / `sync --force`, and a new "Development" section covers `dev:link`/`dev:doctor` and running from source — bringing the gajae-code README's targeted sections to jeo.
+- **Workflow prompts (engine, goal-verifier, deep-interview, critic, architect) tightened against punting and false blocks.** The turn protocol now asks a multi-edit batch to name each change in its `reasoning` and a multi-file task to sketch a todo plan before the first edit, the `web_search` reflex re-searches when sources conflict, and OUTPUT_DISCIPLINE forbids punting with only a disclaimer/cutoff caveat/offer-to-search. The Goal Verifier judges the goal as written with positive per-requirement evidence (MET when satisfied, IMPOSSIBLE only when genuinely unsatisfiable); deep-interview stops filling ambiguity with assumptions yet still lowers its score when dimensions truly resolve; the critic treats softening as signal but never manufactures blocks; the architect notes a clean verdict ≠ no inspection and adds an `Inspected:` line. All escape hatches (single-use done latches, `MAX_RE_BLOCKS`, step-budget hard cap) are unchanged, so no new loop risk.
+
+### Fixed
+- **Attaching an image no longer pushes the input caret several columns past the `[image #N]` tag.** Terminals pad a dragged-and-dropped image path with their own surrounding spaces, and the Ctrl+V clipboard insert added its own separator, so the swapped-in tag ended up flanked by multiple spaces and the caret parked well past it (the "spacebar ×3" feel). The two attach paths now share one tested helper in `src/util/file-attachment.ts`: `normalizeImageTags` collapses the whitespace around every `[image #N]` to exactly one space (trimming line edges, idempotent), `insertImageTag` (Ctrl+V) inserts the tag single-spaced with the caret right after it, and `attachImagePaths` (drag-drop / submit-time) normalizes its output and returns the precise post-tag `cursor`. The live REPL parks the box caret at that offset, so it sits immediately after the tag's single trailing space — ready for the prompt.
+
+### Verified
+- **"Works beside your existing agent or bot" now reflects jeo's real interop surface (all four READMEs).** The table documents `--worktree <name>` (run in an isolated sibling git worktree — `src/commands/launch/tmux.ts` `resolveWorktree`) for the Codex/Claude/Claw rows and `jeo mcp serve` / `jeo mcp tools` (the MCP stdio tool contract — `src/commands/mcp.ts`) for the external-controller/bot row, instead of the prior generic "standard terminal/CLI interfaces" wording.
+- `bun run typecheck` clean; full suite green — 1991 pass / 0 fail across 234 files — including the new `test/dev-link.test.ts` (target/link-dir resolution incl. `JEO_DEV_LINK_DIR` override, PATH splitting, earlier-on-PATH shadow detection, and doctor `linked`/`drift`/`missing` classification), the new `test/memory-search-okf.test.ts` (concept load/score/search, `index.md` disclosure, budget-aware relevance injection, failed-attempt recall), expanded `test/cycle-and-turn-budget.test.ts`, and expanded `test/file-attachment.test.ts` + `test/input-box.test.ts` (whitespace normalization around `[image #N]`, idempotence, `insertImageTag`/`caretAfterTag`/`attachImagePaths` caret offsets, and the end-to-end render proving the caret column lands right after the rendered tag). Real CLI runs verified `dev:link`/`dev:doctor` end-to-end against a temp link dir (symlink + `--version` smoke test, shadow-guard refusal, drift detection, `linked` after linking) and the macOS clipboard image reader end-to-end (`readClipboardImage` decoded a clipboard PNG via the `osascript` fallback).
+
+
 ## [0.7.16] - 2026-06-25
 _Bundled skills get a safe installer: `jeo skills sync` materializes the built-in workflow skills into `~/.jeo/skills`, preserving local edits by default, with a CI-friendly `--check` drift report and a `--force` overwrite._
 

package/README.ja.md

@@ -153,13 +153,13 @@ jeo ultragoal
 
 | ツールまたはボット | 推奨される jeo コマンド | 境界 |
 | ----------- | ----------------------- | -------- |
-| Codex CLI | `jeo --tmux` または `jeo` | 兄弟 tmux セッションまたはインラインで実行されます。 |
-| Claude Code | `jeo --tmux` または `jeo` | jeo は Claude Code の拡張機能にはなりません。 |
+| Codex CLI | `jeo --tmux --worktree <name>` または `jeo` | `--worktree` は jeo が管理する兄弟 git worktree を指定します（basename → 新しいブランチ）。既存のパスは先に `cd` してください。 |
+| Claude Code | `jeo --tmux` または `jeo --tmux --worktree <name>` | jeo は Claude Code の拡張機能にはなりません。 |
 | OpenCode | `jeo` または `jeo --tmux` | 外部ランナーのワークフローのみ。 |
-| Claw Code | `jeo --tmux` | jeo は Claw Code にインストールされたり、置き換えたりしません。 |
-| 外部コントローラー / ボット | `jeo` (またはカスタム統合) | 外部コントローラーは、標準のターミナル/CLI インターフェースを介して jeo を駆動します。 |
+| Claw Code | `jeo --tmux --worktree <name>` | jeo は Claw Code にインストールされたり、置き換えたりしません。 |
+| 外部コントローラー / ボット | `jeo mcp serve` (MCP stdio サーバー) | 外部コントローラーはスクロールバックのスクレイピングではなく、MCP ツール契約を介して jeo を駆動します。 |
 
-`-q`/`--quiet` (または `JEO_QUIET=1`) を追加すると、起動バナー・ウェルカムアニメーション・リリースノート・再開ヒントが抑制され、jeo を別のエージェントと並べて実行したりボットから駆動したりできます。`-p`/`--print` は quiet を含みます。
+`--worktree <name>` は隔離された兄弟 git worktree で jeo を実行するため（パスがあれば再利用、なければ basename ブランチで作成）、リスクのある作業やレビュー対象の作業がメインのチェックアウトに触れることはありません。`jeo mcp serve` は stdio を介して MCP 対応のあらゆるコントローラーに jeo のツールを公開します（`jeo mcp tools` で一覧表示）。`-q`/`--quiet` (または `JEO_QUIET=1`) を追加すると、起動バナー・ウェルカムアニメーション・リリースノート・再開ヒントが抑制され、jeo を別のエージェントと並べて実行したりボットから駆動したりできます。`-p`/`--print` は quiet を含みます。
 
 
 ## ローカルモデル
@@ -205,11 +205,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.17]** (2026-06-25) — Developer workflow parity (gjc `dev:link`/`dev:doctor`, adapted for jeo's zero-native-dep Bun runtime): the global `jeo` command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when `jeo` resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact.
 - **[0.7.16]** (2026-06-25) — Bundled skills get a safe installer: `jeo skills sync` materializes the built-in workflow skills into `~/.jeo/skills`, preserving local edits by default, with a CI-friendly `--check` drift report and a `--force` overwrite.
 - **[0.7.15]** (2026-06-25) — Rollback release: the runtime source and test suite are restored to the **0.7.9** state. The intervening 0.7.10–0.7.14 runtime changes (quiet-mode/`-q`, `/resume` transcript rework, `mutatedFiles` plumbing, Ollama `num_ctx`, tmux REPL reaping, and related engine/provider/TUI edits) are reverted. Published as a new version because npm cannot re-issue an existing version number; `latest` now serves code identical to 0.7.9.
 - **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
-- **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -153,13 +153,13 @@ jeo ultragoal
 
 | 도구 또는 봇 | 권장 jeo 명령 | 경계 |
 | ----------- | ----------------------- | -------- |
-| Codex CLI | `jeo --tmux` 또는 `jeo` | 형제 tmux 세션 또는 인라인으로 실행됩니다. |
-| Claude Code | `jeo --tmux` 또는 `jeo` | jeo는 Claude Code 확장 프로그램이 되지 않습니다. |
+| Codex CLI | `jeo --tmux --worktree <name>` 또는 `jeo` | `--worktree`는 jeo가 관리하는 형제 git worktree를 지정합니다(basename → 새 브랜치). 기존 경로는 먼저 `cd`로 이동하세요. |
+| Claude Code | `jeo --tmux` 또는 `jeo --tmux --worktree <name>` | jeo는 Claude Code 확장 프로그램이 되지 않습니다. |
 | OpenCode | `jeo` 또는 `jeo --tmux` | 현재는 외부 러너 워크플로만 지원합니다. |
-| Claw Code | `jeo --tmux` | jeo는 Claw Code에 설치되거나 대체되지 않습니다. |
-| 외부 컨트롤러 / 봇 | `jeo` (또는 사용자 정의 통합) | 외부 컨트롤러는 표준 터미널/CLI 인터페이스를 통해 jeo를 구동합니다. |
+| Claw Code | `jeo --tmux --worktree <name>` | jeo는 Claw Code에 설치되거나 대체되지 않습니다. |
+| 외부 컨트롤러 / 봇 | `jeo mcp serve` (MCP stdio 서버) | 외부 컨트롤러는 스크롤백 스크래핑이 아니라 MCP 도구 계약을 통해 jeo를 구동합니다. |
 
-`-q`/`--quiet` (또는 `JEO_QUIET=1`)를 추가하면 시작 배너, 환영 애니메이션, 릴리스 노트, 재개 힌트가 억제되어 jeo를 다른 에이전트와 나란히 실행하거나 봇으로 구동할 수 있습니다. `-p`/`--print`는 quiet를 함의합니다.
+`--worktree <name>`는 격리된 형제 git worktree에서 jeo를 실행하므로(경로가 있으면 재사용, 없으면 basename 브랜치로 생성) 위험하거나 검토가 필요한 작업이 메인 체크아웃을 건드리지 않습니다. `jeo mcp serve`는 stdio를 통해 MCP를 지원하는 모든 컨트롤러에 jeo의 도구를 노출합니다(`jeo mcp tools`로 목록 확인). `-q`/`--quiet` (또는 `JEO_QUIET=1`)를 추가하면 시작 배너, 환영 애니메이션, 릴리스 노트, 재개 힌트가 억제되어 jeo를 다른 에이전트와 나란히 실행하거나 봇으로 구동할 수 있습니다. `-p`/`--print`는 quiet를 함의합니다.
 
 
 ## 로컬 모델
@@ -205,11 +205,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.17]** (2026-06-25) — Developer workflow parity (gjc `dev:link`/`dev:doctor`, adapted for jeo's zero-native-dep Bun runtime): the global `jeo` command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when `jeo` resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact.
 - **[0.7.16]** (2026-06-25) — Bundled skills get a safe installer: `jeo skills sync` materializes the built-in workflow skills into `~/.jeo/skills`, preserving local edits by default, with a CI-friendly `--check` drift report and a `--force` overwrite.
 - **[0.7.15]** (2026-06-25) — Rollback release: the runtime source and test suite are restored to the **0.7.9** state. The intervening 0.7.10–0.7.14 runtime changes (quiet-mode/`-q`, `/resume` transcript rework, `mutatedFiles` plumbing, Ollama `num_ctx`, tmux REPL reaping, and related engine/provider/TUI edits) are reverted. Published as a new version because npm cannot re-issue an existing version number; `latest` now serves code identical to 0.7.9.
 - **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
-- **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -154,13 +154,13 @@ Non-zero hook output is appended to the tool result the model reads (deduped per
 
 | Tool or bot | Recommended jeo command | Boundary |
 | ----------- | ----------------------- | -------- |
-| Codex CLI | `jeo --tmux` or `jeo` | Runs in a sibling tmux session or inline. |
-| Claude Code | `jeo --tmux` or `jeo` | jeo does not become a Claude Code extension. |
+| Codex CLI | `jeo --tmux --worktree <name>` or `jeo` | `--worktree` names a jeo-managed sibling git worktree (basename → new branch); for an existing path, `cd` there first. |
+| Claude Code | `jeo --tmux` or `jeo --tmux --worktree <name>` | jeo does not become a Claude Code extension. |
 | OpenCode | `jeo` or `jeo --tmux` | External-runner workflow only. |
-| Claw Code | `jeo --tmux` | jeo does not install into or replace Claw Code. |
-| External controller / bot | `jeo` (or custom integrations) | External controllers drive jeo through standard terminal/CLI interfaces. |
+| Claw Code | `jeo --tmux --worktree <name>` | jeo does not install into or replace Claw Code. |
+| External controller / bot | `jeo mcp serve` (MCP stdio server) | External controllers drive jeo over the MCP tool contract, not scrollback scraping. |
 
-Add `-q`/`--quiet` (or `JEO_QUIET=1`) to suppress startup banners, welcome animation, release notes, and resume hints so jeo can run cleanly beside another agent or be driven by a bot. `-p`/`--print` implies quiet.
+`--worktree <name>` runs jeo in an isolated sibling git worktree (reused if the path exists, else created on a branch named after the basename) so risky or reviewable work never touches your main checkout. `jeo mcp serve` exposes jeo's tools to any MCP-capable controller over stdio (`jeo mcp tools` lists them). Add `-q`/`--quiet` (or `JEO_QUIET=1`) to suppress startup banners, the welcome animation, release notes, and resume hints so jeo runs cleanly beside another agent or is driven by a bot — `-p`/`--print` implies quiet.
 
 
 ## Local models
@@ -191,8 +191,33 @@ JEO_TOOL_OUTPUT_MAX=4000        # model-visible tool output cap (full output spi
 
 Retry behavior is tunable via `retry` in `~/.jeo/config.json` (`requestMaxRetries`, `streamMaxRetries`, `rateLimitRetries`, `failFastStatuses`, …). The step budget is dynamic by default — it extends while recent tool calls show novel progress and consolidates with a wrap-up when stalled; `--max-steps N` restores a bounded flow.
 
+## Skill migration and bundled skill inspection
+
+When moving a workflow into jeo, inspect the bundled defaults before installing or overwriting anything:
+
+```bash
+jeo skills list                 # bundled + user + project skills, with discovery dirs
+jeo skills read ralplan         # print one skill's full SKILL.md
+jeo skills sync --check         # report drift vs ~/.jeo/skills (non-zero exit on drift)
+```
+
+`jeo skills sync` installs the bundled workflow skills (deep-interview, deep-dive, ralplan, team, ultragoal) into `~/.jeo/skills` and **preserves existing local files by default** — a differing local copy is reported as `preserved`, never clobbered. If `--check` flags a missing or different file, compare it with `jeo skills read <name>` first; use `jeo skills sync --force` only when you intentionally want to replace local default workflow skill files. Target a different dir with a trailing path argument (or `JEO_CONFIG_DIR`), and add `--json` for the structured `SkillSyncResult`.
+
+## Development
+
+jeo is pure TypeScript on Bun with **zero native dependencies**, so the global `jeo` command can run this checkout's source directly — no build step, hot to every edit.
+
+```bash
+bun install
+bun run dev:link            # symlink `jeo` -> <repo>/src/cli.ts into ~/.local/bin
+bun run dev:doctor          # report whether global `jeo` runs this source (linked/drift/missing)
+```
+
+`dev:link` refuses to proceed if another `jeo` shadows the managed link earlier on `PATH` (override the destination with `JEO_DEV_LINK_DIR`) and runs a `--version` smoke test. `dev:doctor` exits non-zero when the resolved `jeo` is a compiled binary or an installed copy rather than this source. Run from source without linking via `bun src/cli.ts --help`. Bundled workflow skills live in source at `src/prompts/skills/<name>/SKILL.md`; verify with `bun run typecheck` and `bun test`.
+
 ## Publishing
 
+
 CI publishes via `.github/workflows/npm-publish.yml` — triggered by a published GitHub release, or manually with `workflow_dispatch` (optional dry-run). The workflow typechecks, tests, verifies the token (`npm whoami`), then runs `npm publish --provenance`.
 
 Required npm token permissions (repository secret `NPM_TOKEN`):
@@ -207,11 +232,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.17]** (2026-06-25) — Developer workflow parity (gjc `dev:link`/`dev:doctor`, adapted for jeo's zero-native-dep Bun runtime): the global `jeo` command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when `jeo` resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact.
 - **[0.7.16]** (2026-06-25) — Bundled skills get a safe installer: `jeo skills sync` materializes the built-in workflow skills into `~/.jeo/skills`, preserving local edits by default, with a CI-friendly `--check` drift report and a `--force` overwrite.
 - **[0.7.15]** (2026-06-25) — Rollback release: the runtime source and test suite are restored to the **0.7.9** state. The intervening 0.7.10–0.7.14 runtime changes (quiet-mode/`-q`, `/resume` transcript rework, `mutatedFiles` plumbing, Ollama `num_ctx`, tmux REPL reaping, and related engine/provider/TUI edits) are reverted. Published as a new version because npm cannot re-issue an existing version number; `latest` now serves code identical to 0.7.9.
 - **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
-- **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -153,13 +153,13 @@ jeo ultragoal
 
 | 工具或机器人 | 推荐的 jeo 命令 | 边界 |
 | ----------- | ----------------------- | -------- |
-| Codex CLI | `jeo --tmux` 或 `jeo` | 在同级 tmux 会话中运行或内联运行。 |
-| Claude Code | `jeo --tmux` 或 `jeo` | jeo 不会成为 Claude Code 的扩展。 |
+| Codex CLI | `jeo --tmux --worktree <name>` 或 `jeo` | `--worktree` 指定一个由 jeo 管理的同级 git worktree（basename → 新分支）；对于已有路径，请先 `cd` 进入。 |
+| Claude Code | `jeo --tmux` 或 `jeo --tmux --worktree <name>` | jeo 不会成为 Claude Code 的扩展。 |
 | OpenCode | `jeo` 或 `jeo --tmux` | 仅限外部运行器工作流。 |
-| Claw Code | `jeo --tmux` | jeo 不会安装到或替换 Claw Code。 |
-| 外部控制器 / 机器人 | `jeo` (或自定义集成) | 外部控制器通过标准终端/CLI 接口驱动 jeo。 |
+| Claw Code | `jeo --tmux --worktree <name>` | jeo 不会安装到或替换 Claw Code。 |
+| 外部控制器 / 机器人 | `jeo mcp serve` (MCP stdio 服务器) | 外部控制器通过 MCP 工具契约驱动 jeo，而非抓取滚动回显。 |
 
-添加 `-q`/`--quiet`（或 `JEO_QUIET=1`）可抑制启动横幅、欢迎动画、发布说明和恢复提示，使 jeo 能够与其他代理并行运行或由机器人驱动。`-p`/`--print` 隐含 quiet。
+`--worktree <name>` 在隔离的同级 git worktree 中运行 jeo（路径存在则复用，否则以 basename 分支创建），因此有风险或需审查的工作绝不会触及您的主检出。`jeo mcp serve` 通过 stdio 向任何支持 MCP 的控制器公开 jeo 的工具（用 `jeo mcp tools` 列出）。添加 `-q`/`--quiet`（或 `JEO_QUIET=1`）可抑制启动横幅、欢迎动画、发布说明和恢复提示，使 jeo 能够与其他代理并行运行或由机器人驱动。`-p`/`--print` 隐含 quiet。
 
 
 ## 本地模型
@@ -205,11 +205,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.17]** (2026-06-25) — Developer workflow parity (gjc `dev:link`/`dev:doctor`, adapted for jeo's zero-native-dep Bun runtime): the global `jeo` command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when `jeo` resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact.
 - **[0.7.16]** (2026-06-25) — Bundled skills get a safe installer: `jeo skills sync` materializes the built-in workflow skills into `~/.jeo/skills`, preserving local edits by default, with a CI-friendly `--check` drift report and a `--force` overwrite.
 - **[0.7.15]** (2026-06-25) — Rollback release: the runtime source and test suite are restored to the **0.7.9** state. The intervening 0.7.10–0.7.14 runtime changes (quiet-mode/`-q`, `/resume` transcript rework, `mutatedFiles` plumbing, Ollama `num_ctx`, tmux REPL reaping, and related engine/provider/TUI edits) are reverted. Published as a new version because npm cannot re-issue an existing version number; `latest` now serves code identical to 0.7.9.
 - **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
-- **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.16",
+  "version": "0.7.17",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",
@@ -52,7 +52,9 @@
     "publish:npm": "npm publish --access public --registry https://registry.npmjs.org/",
     "changelog:sync": "bun scripts/sync-changelog.ts",
     "test": "bun test",
-    "verify:tmux": "bash scripts/tmux-verify.sh"
+    "verify:tmux": "bash scripts/tmux-verify.sh",
+    "dev:link": "bun scripts/dev-link.ts link",
+    "dev:doctor": "bun scripts/dev-link.ts doctor"
   },
   "dependencies": {
     "zod": "^3.24.1",

package/src/agent/AGENTS.md

@@ -17,8 +17,8 @@ The core runtime loop, tool registry, session management, and state persistence
 | `hooks.ts` | Brief description of purpose |
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
-| `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`isVerificationSignal`, `repeatHint`, `classifyDoneGate`) consumed by `engine.ts` |
-| `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
+| `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`isVerificationSignal`, `repeatHint`, `classifyDoneGate` — incl. `done_stale_verification` for a passing test/build that predates the last edit) consumed by `engine.ts` |
+| `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection (failure-first `priorityOrder` + pinned-invariant reserved budget), mid-loop `recordFailedAttempt` capture, shared `upsertConceptFile` writer, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
 | `memory-okf.ts` | OKF v0.1 format layer: frontmatter parse/serialize, concept IDs, conformance validation |
 | `memory-graph.ts` | Concept cross-link graph: build/expand (1-hop search), broken-link-tolerant lint, optional graphify detection |
 | `model-recency.ts` | Brief description of purpose |

package/src/agent/engine.ts

@@ -105,9 +105,9 @@ export const TOOL_PROTOCOL = [
   "",
   "Alternatively, you may batch up to 6 independent calls in a single turn using the following format:",
   '{ "reasoning": "<one short sentence>", "tools": [{ "tool": "<name>", "arguments": { ... } }, ...] }',
-  "Batch only independent calls; NEVER batch 'done', and NEVER put a mutating tool (write/edit/bash) after another mutating tool in one batch whose inputs depend on the earlier one.",
-  "Tool calibration: scale calls to difficulty — one for a known fact, a few for a normal task, more only when evidence is genuinely missing. Locate before you open: search/find first, then read the hit, instead of guessing paths.",
-  "web_search reflex: if the request hinges on a name, version, library, or event you do not actually recognize, search before answering instead of guessing; never claim a result's absence proves nonexistence.",
+  "Batch only independent calls; NEVER batch 'done', and NEVER put a mutating tool (write/edit/bash) after another mutating tool in one batch whose inputs depend on the earlier one. In a multi-edit batch, let the turn `reasoning` name each change — not a vague one-liner.",
+  "Tool calibration: scale calls to difficulty — one for a known fact, a few for a normal task, more only when evidence is genuinely missing. For multi-file or multi-step work, sketch a short plan (todo) before the first edit; a one-line change goes straight to the edit. Locate before you open: search/find first, then read the hit, instead of guessing paths.",
+  "web_search reflex: if the request hinges on a name, version, library, or event you do not actually recognize, search before answering instead of guessing; never claim a result's absence proves nonexistence. When sources conflict or look incomplete, run another targeted search to disambiguate rather than picking one at random.",
   "Quoting fetched/searched text: paraphrase by default — quote at most one short phrase per source, cite it, and never paste long passages.",
 ].join("\n");
 
@@ -165,6 +165,7 @@ export const OUTPUT_DISCIPLINE = [
   "- When using lists, ensure each bullet carries a complete thought; avoid fragmented or shredded reports.",
   "- Don't stall on ambiguity: make reasonable assumptions and ask at most one clarifying question if absolutely necessary.",
   "- Report only what is done or in progress; never announce future work instead of doing it.",
+  "- Give a substantive answer first; never punt with only a disclaimer, a knowledge-cutoff caveat, or an offer to search — answer with what you have, then note the caveat.",
   "- Match reply length to the task: a one-line change gets a one-line report.",
 ].join("\n");
 
@@ -272,6 +273,10 @@ export interface AgentLoopResult {
   doneReason?: string;
   /** Summed provider token usage across the turn's steps, when reported. */
   usage?: { inputTokens: number; outputTokens: number };
+  /** Set ONLY when the turn ended in a guard-detected dead end the model could not
+   *  recover from (repeated/cycled/consecutively-failing calls). Lets the caller
+   *  capture the stall into failure memory; `undefined` for done/budget/cancelled. */
+  stopClass?: "consecutive_failure" | "cycle" | "repeat";
 }
 
 
@@ -369,7 +374,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   // "Stopped: …" — throwing away everything found this turn — do ONE final no-tools
   // call asking the model to answer with what it already has. Mirrors the
   // budget-exhaustion wrap-up below. Best-effort: falls back to the plain stop.
-  const consolidateStop = async (stopReason: string): Promise<AgentLoopResult> => {
+  const consolidateStop = async (stopReason: string, stopClass: AgentLoopResult["stopClass"]): Promise<AgentLoopResult> => {
     try {
       if (!opts.signal?.aborted) {
         const wrapUp = await invokeCallLlm(
@@ -391,12 +396,13 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           return finish({
             done: false,
             steps: step,
+            stopClass,
             doneReason: `${consolidated}\n\n(Stopped: ${stopReason} — consolidated answer above from what was found; continue with a follow-up request)`,
           });
         }
       }
     } catch { /* best-effort; fall through to the plain stop message */ }
-    return finish({ done: false, steps: step, doneReason: `Stopped: ${stopReason}` });
+    return finish({ done: false, steps: step, stopClass, doneReason: `Stopped: ${stopReason}` });
   };
   // No-progress guard: weak/local models often repeat the same tool call without
   // ever emitting `done`. Two escalating corrections (B), then a consolidated stop.
@@ -414,6 +420,12 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   // doc/config changes where verification is genuinely not applicable).
   let sawMutation = false;
   let sawVerification = false;
+  // Monotonic ordering of mutation vs. verification events so the done gate can
+  // tell a STALE verification (passing test/build that predates the last edit)
+  // from a fresh one. A single counter captures intra-batch order too.
+  let mutVerSeq = 0;
+  let lastMutationSeq = 0;
+  let lastVerificationSeq = 0;
   let donePushbackUsed = false;
   // Caller-owned done gate (onBeforeDone) — also strictly once per turn.
   let beforeDoneNudgeUsed = false;
@@ -717,7 +729,12 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       // done-verification gate — jeo's descendant of gjc's ultragoal-guard completion
       // state machine (plan/gjc-inheritance.md B4). The classifier owns the JUDGMENT
       // (which named state, which message); the loop owns the once-pushback latch.
-      const doneGate = classifyDoneGate({ sawMutation, sawVerification, pendingHookFailure });
+      const doneGate = classifyDoneGate({
+        sawMutation,
+        sawVerification,
+        verificationStale: sawMutation && lastMutationSeq > lastVerificationSeq,
+        pendingHookFailure,
+      });
       if (doneGate.block && !donePushbackUsed) {
         donePushbackUsed = true; // second done always passes — escape hatch
         pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
@@ -805,7 +822,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     }
     if (repeatCount >= MAX_REPEAT) {
       const what = toolCalls.length === 1 ? `the same '${toolCalls[0].tool}' call` : "the same tool calls";
-      return await consolidateStop(`repeated ${what} ${MAX_REPEAT}× even after explicit corrections (the model never signaled done)`);
+      return await consolidateStop(`repeated ${what} ${MAX_REPEAT}× even after explicit corrections (the model never signaled done)`, "repeat");
     }
 
     // Cycle guard: an A↔B (or A↔B↔C-minus-one) alternation never trips the
@@ -833,7 +850,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         step++;
         continue;
       }
-      return await consolidateStop(`the model cycled through the same tool calls for ${CYCLE_WINDOW} consecutive steps even after an explicit correction (it never signaled done)`);
+      return await consolidateStop(`the model cycled through the same tool calls for ${CYCLE_WINDOW} consecutive steps even after an explicit correction (it never signaled done)`, "cycle");
     }
 
     // Helper to execute a single tool call
@@ -1037,15 +1054,20 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     }
     // done-verification guard bookkeeping: write/edit successes mark the turn as
     // mutating; a successful bash whose command/output looks like a test/build run
-    // counts as verification. A verification AFTER the last mutation is what the
-    // done guard wants, but order-insensitive tracking keeps it one-pushback simple.
+    // counts as verification. A monotonic seq records ORDER so the done gate can
+    // reject a verification that predates the last mutation (stale evidence).
     for (let i = 0; i < toolCalls.length; i++) {
       if (!results[i].executed || !results[i].success) continue;
       const t = toolCalls[i].tool;
-      if (t === "write" || t === "edit") sawMutation = true;
-      else if (t === "bash") {
+      if (t === "write" || t === "edit") {
+        sawMutation = true;
+        lastMutationSeq = ++mutVerSeq;
+      } else if (t === "bash") {
         const cmd = String(toolCalls[i].arguments?.command ?? "");
-        if (isVerificationSignal(cmd, results[i].output)) sawVerification = true;
+        if (isVerificationSignal(cmd, results[i].output)) {
+          sawVerification = true;
+          lastVerificationSeq = ++mutVerSeq;
+        }
       }
     }
     // F6 (round 4 architect, Low): judge the step by its NON-TRIVIAL calls — a
@@ -1069,6 +1091,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       return finish({
         done: false,
         steps: step,
+        stopClass: "consecutive_failure",
         doneReason: stopMsg,
       });
     }

package/src/agent/goal-verifier.ts

@@ -33,6 +33,12 @@ Analyze the transcript carefully. Pay attention to:
 2. What actions the agent took (tool calls, file modifications, tests run).
 3. The final outcome and verification results.
 
+Verdict discipline:
+- Judge the goal exactly as written. Do NOT reframe, narrow, or reinterpret it to fit what the agent happened to build — if the goal as stated is not satisfied, that is NOT_MET, and name precisely what is missing.
+- Require positive evidence per requirement: cite the concrete command, test, or file change that shows it was satisfied. The mere absence of an observed failure is NOT proof of success.
+- Do not invent requirements beyond the stated goal. When every part of the goal as written has positive evidence, return MET — withholding MET to demand unrequested extras is itself an error.
+- Reserve IMPOSSIBLE for goals that cannot be satisfied as specified (self-contradictory, or blocked by missing credentials/services), not for goals that are merely incomplete.
+
 You must respond with a JSON object containing:
 {
   "verdict": "MET" | "NOT_MET" | "IMPOSSIBLE",

package/src/agent/loop-guards.ts

@@ -27,6 +27,7 @@ export type GuardState =
   | "context_overflow_retry" // provider reported context overflow → ONE trim + retry
   | "refusal_retry" // transient safety refusal → bounded resend ladder
   | "done_unverified" // mutated files, no verification signal → pushback on done
+  | "done_stale_verification" // verified, then mutated again → re-verify before done
   | "done_hook_failing" // post-turn hook still failing → pushback on done
   | "done_ok"; // done accepted — the turn is finished
 
@@ -100,13 +101,19 @@ export interface DoneGateInput {
   sawMutation: boolean;
   /** A test/build/typecheck/lint command succeeded this turn. */
   sawVerification: boolean;
+  /**
+   * A mutation landed AFTER the most recent successful verification — so the
+   * passing test/build no longer reflects the current tree. Optional; defaults
+   * to false, in which case the gate uses the order-insensitive `sawVerification`.
+   */
+  verificationStale?: boolean;
   /** The run-command of the most recent still-failing post-turn hook, or null. */
   pendingHookFailure: string | null;
 }
 
 /** Verdict from {@link classifyDoneGate}: whether to bounce `done`, and the message. */
 export interface DoneGateVerdict {
-  state: Extract<GuardState, "done_ok" | "done_unverified" | "done_hook_failing">;
+  state: Extract<GuardState, "done_ok" | "done_unverified" | "done_stale_verification" | "done_hook_failing">;
   /** When true, `done` should be bounced ONCE with `message` (the caller owns the once-gate). */
   block: boolean;
   /** Corrective message to push back on `done`; empty when `state === "done_ok"`. */
@@ -117,13 +124,15 @@ export interface DoneGateVerdict {
  * Classify whether a `done` should be accepted or bounced — the direct descendant of
  * gjc's `ultragoal-guard` completion gate (plan/gjc-inheritance.md B4).
  *
- * A turn that MUTATED files but has either NO verification signal or a still-failing
- * post-turn hook is blocked ONCE. The caller owns the single-pushback latch; a second
- * `done` always passes (the escape hatch for genuinely-unverifiable docs/config changes).
+ * A turn that MUTATED files is blocked ONCE when its verification is missing
+ * (no test/build signal), STALE (a passing run that predates the last edit), or
+ * a post-turn hook is still failing. The caller owns the single-pushback latch; a
+ * second `done` always passes (the escape hatch for unverifiable docs/config changes).
  */
 export function classifyDoneGate(input: DoneGateInput): DoneGateVerdict {
   const hookFailing = input.pendingHookFailure !== null;
-  const block = input.sawMutation && (!input.sawVerification || hookFailing);
+  const stale = input.sawVerification && input.verificationStale === true;
+  const block = input.sawMutation && (!input.sawVerification || stale || hookFailing);
   if (!block) return { state: "done_ok", block: false, message: "" };
   if (hookFailing) {
     return {
@@ -135,6 +144,16 @@ export function classifyDoneGate(input: DoneGateInput): DoneGateVerdict {
         "If the hook failure is a false positive, call done again and say why in the reason.",
     };
   }
+  if (stale) {
+    return {
+      state: "done_stale_verification",
+      block: true,
+      message:
+        "You verified earlier, but then modified files again — your last passing test/build no longer reflects the current tree. " +
+        "Re-run the narrowest verification command against the latest changes, then call done. " +
+        "If the later edits are verification-irrelevant (docs/config-only), call done again and say why in the reason.",
+    };
+  }
   return {
     state: "done_unverified",
     block: true,

package/src/agent/memory.ts

@@ -202,6 +202,10 @@ export interface Concept {
   tags: string[];
   /** high | medium | low — distiller defaults to "high"; drives core selection. */
   confidence: string;
+  /** Load-bearing invariant (frontmatter `pinned: true`): selected into the injection
+   *  budget BEFORE any query/recency fill, so the cap can never evict it (philosophy
+   *  synthesis R8 / consensus #3 — pinned invariants survive on a reserved budget). */
+  pinned: boolean;
   /** Bundle-relative path, e.g. `commands/bun-test.md`. */
   relPath: string;
 }
@@ -284,6 +288,7 @@ async function loadConceptsFromBundle(bundleDir: string): Promise<Concept[]> {
       body: parsed.body.trim(),
       tags: Array.isArray(fm.tags) ? fm.tags.filter((t): t is string => typeof t === "string") : [],
       confidence: typeof fm.confidence === "string" ? fm.confidence : "high",
+      pinned: fm.pinned === true,
       relPath,
     };
     cacheParsedConcept(file, sig, concept);
@@ -339,10 +344,16 @@ export function searchConcepts(concepts: Concept[], query: string): { concept: C
     .sort((a, b) => b.score - a.score);
 }
 
-/** Priority order for injection: high-confidence "core" concepts first, then by
- *  query relevance (descending), then concepts the relevant ones LINK TO (1-hop
- *  graph expansion — Sprint 04: a directly-hit concept pulls its neighbours in as
- *  context ahead of unrelated noise), preserving input order as a stable tiebreak. */
+/** Priority order for injection. Failure-first: a query-relevant FailedAttempt is
+ *  surfaced AHEAD of everything else — resurfacing a known dead end is higher-leverage
+ *  than reinforcing what already works ("못하는 게 없도록" — close the gaps, don't just
+ *  polish strengths), and it is the mechanism by which the loop gets more precise the
+ *  more it repeats (llm-wiki: accumulated failure knowledge sharpens future runs). Then
+ *  high-confidence "core" concepts, then query relevance (descending), then concepts the
+ *  relevant ones LINK TO (1-hop graph expansion — Sprint 04: a directly-hit concept pulls
+ *  its neighbours in as context ahead of unrelated noise), preserving input order as a
+ *  stable tiebreak. The failure boost only fires when the query actually hits the concept
+ *  (score > 0), so an unrelated FailedAttempt never crowds out relevant context. */
 function priorityOrder(concepts: Concept[], query?: string): Concept[] {
   const tokens = tokenize(query);
   // 1-hop graph expansion: seed from concepts the query directly hits, then mark
@@ -354,14 +365,22 @@ function priorityOrder(concepts: Concept[], query?: string): Concept[] {
     for (const id of expandByGraph(seeds, graph, 1)) related.add(id);
   }
   return concepts
-    .map((concept, i) => ({
-      concept,
-      i,
-      core: concept.confidence === "high",
-      score: scoreConcept(concept, tokens),
-      related: related.has(conceptId(concept.relPath)),
-    }))
+    .map((concept, i) => {
+      const score = scoreConcept(concept, tokens);
+      return {
+        concept,
+        i,
+        // Query-relevant past failure → resurface first so the loop is reminded of
+        // what NOT to repeat for the current task. Gated on score > 0: a stale,
+        // unrelated dead end stays out of the way.
+        failure: concept.type === "FailedAttempt" && score > 0,
+        core: concept.confidence === "high",
+        score,
+        related: related.has(conceptId(concept.relPath)),
+      };
+    })
     .sort((a, b) => {
+      if (a.failure !== b.failure) return a.failure ? -1 : 1;
       if (a.core !== b.core) return a.core ? -1 : 1;
       if (b.score !== a.score) return b.score - a.score;
       if (a.related !== b.related) return a.related ? -1 : 1;
@@ -404,14 +423,22 @@ function renderConcepts(concepts: Concept[]): string {
 
 /** Greedily select concepts (in priority order) whose grouped render stays within
  *  `budget` chars, dropping the lowest-priority concepts first. At least the
- *  top-priority concept is always kept (the framing/backstop cap still applies). */
+ *  top-priority concept is always kept (the framing/backstop cap still applies).
+ *
+ *  Pinned (load-bearing) invariants get a RESERVED budget: they are selected FIRST,
+ *  before any query/recency fill, so a tight cap can never evict an invariant the
+ *  gates depend on (philosophy-synthesis consensus #3). The remaining budget then
+ *  holds the failure-first / core / query-relevant fill. */
 function selectWithinBudget(concepts: Concept[], query: string | undefined, budget: number): Concept[] {
-  const ordered = priorityOrder(concepts, query);
   const selected: Concept[] = [];
-  for (const c of ordered) {
-    if (renderConcepts([...selected, c]).length <= budget) selected.push(c);
-  }
-  if (selected.length === 0 && ordered.length > 0) selected.push(ordered[0]!);
+  const take = (pool: Concept[]) => {
+    for (const c of priorityOrder(pool, query)) {
+      if (renderConcepts([...selected, c]).length <= budget) selected.push(c);
+    }
+  };
+  take(concepts.filter(c => c.pinned)); // reserved budget: invariants survive the cap
+  take(concepts.filter(c => !c.pinned)); // recency/query fill in the remaining budget
+  if (selected.length === 0 && concepts.length > 0) selected.push(priorityOrder(concepts, query)[0]!);
   return selected;
 }
 
@@ -610,6 +637,55 @@ async function cleanupStalePendingFiles(dir: string): Promise<void> {
   }
 }
 
+/** Upsert ONE concept document into the bundle: resolve its file (dedup by title —
+ *  same title overwrites in place, a colliding slug gets a numeric suffix), merge
+ *  over any existing frontmatter, and atomically write it. The single source of
+ *  truth for a concept file's on-disk shape — shared by the session-exit distiller
+ *  and the deterministic recordFailedAttempt path. Does NOT touch index/log (callers
+ *  batch that). Assumes a non-empty title; unknown types fall back to facts/. */
+async function upsertConceptFile(
+  bundleDir: string,
+  c: { type: string; title: string; description?: string; body?: string; tags?: string[]; confidence?: string; links?: string[]; pinned?: boolean },
+): Promise<string> {
+  const dir = DIR_BY_TYPE[c.type] ?? "facts";
+  await fs.mkdir(path.join(bundleDir, dir), { recursive: true });
+  let slug = slugify(c.title);
+  let relPath = `${dir}/${slug}.md`;
+  let fullPath = path.join(bundleDir, relPath);
+  let suffix = 1;
+  while (true) {
+    try {
+      if ((parseConcept(await fs.readFile(fullPath, "utf-8")).frontmatter.title || "") === c.title) break;
+      slug = `${slugify(c.title)}-${suffix}`;
+      relPath = `${dir}/${slug}.md`;
+      fullPath = path.join(bundleDir, relPath);
+      suffix++;
+    } catch {
+      break;
+    }
+  }
+  let existingFm: Record<string, unknown> = {};
+  try {
+    existingFm = parseConcept(await fs.readFile(fullPath, "utf-8")).frontmatter as Record<string, unknown>;
+  } catch {}
+  const frontmatter = {
+    ...existingFm,
+    type: c.type,
+    title: c.title,
+    description: c.description ?? "",
+    tags: c.tags ?? [],
+    timestamp: new Date().toISOString(),
+    confidence: c.confidence ?? "high",
+    last_verified: new Date().toISOString().split("T")[0],
+    links: c.links ?? [],
+    ...(c.pinned ? { pinned: true } : {}),
+  };
+  const tmpPath = `${fullPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, serializeConcept(frontmatter, c.body ?? ""), "utf-8");
+  await fs.rename(tmpPath, fullPath);
+  return relPath;
+}
+
 export async function distillSessionMemory(
   history: Message[],
   cwd: string,
@@ -721,57 +797,15 @@ export async function distillSessionMemory(
         const title = typeof concept.title === "string" ? concept.title.trim() : "";
         if (!type || !title) continue;
         try {
-          // Unknown types fall back to facts/ (lenient — OKF tolerates extra types).
-          const dir = DIR_BY_TYPE[type] ?? "facts";
-
-          const targetDir = path.join(bundleDir, dir);
-          await fs.mkdir(targetDir, { recursive: true });
-
-          let slug = slugify(title);
-          let relPath = `${dir}/${slug}.md`;
-          let fullPath = path.join(bundleDir, relPath);
-
-          let suffix = 1;
-          while (true) {
-            try {
-              const existingContent = await fs.readFile(fullPath, "utf-8");
-              const parsed = parseConcept(existingContent);
-              const existingTitle = parsed.frontmatter.title || "";
-              if (existingTitle === title) {
-                break;
-              }
-              slug = `${slugify(title)}-${suffix}`;
-              relPath = `${dir}/${slug}.md`;
-              fullPath = path.join(bundleDir, relPath);
-              suffix++;
-            } catch {
-              break;
-            }
-          }
-
-          let existingFm = {};
-          try {
-            const existingContent = await fs.readFile(fullPath, "utf-8");
-            existingFm = parseConcept(existingContent).frontmatter;
-          } catch {}
-
-          const frontmatter = {
-            ...existingFm,
-            type,
+          await upsertConceptFile(bundleDir, {
+            type, // unknown types fall back to facts/ inside the helper (lenient)
             title,
             description: typeof concept.description === "string" ? concept.description : "",
+            body: typeof concept.body === "string" ? concept.body : "",
             tags: Array.isArray(concept.tags) ? concept.tags.filter((t): t is string => typeof t === "string") : [],
-            timestamp: new Date().toISOString(),
             confidence: typeof concept.confidence === "string" ? concept.confidence : "high",
-            last_verified: new Date().toISOString().split("T")[0],
             links: Array.isArray(concept.links) ? concept.links.filter((l): l is string => typeof l === "string") : [],
-          };
-
-          const serialized = serializeConcept(frontmatter, typeof concept.body === "string" ? concept.body : "");
-          const tmpPath = `${fullPath}.tmp-${process.pid}`;
-          await fs.writeFile(tmpPath, serialized, "utf-8");
-          await fs.rename(tmpPath, fullPath);
-
+          });
           updatedConcepts.push({ title, type });
         } catch {
           // Skip just this concept; keep distilling the rest of the batch.
@@ -819,6 +853,46 @@ export async function distillSessionMemory(
   }
 }
 
+/** Mid-session, deterministic (no-LLM) capture of a dead end into the OKF bundle.
+ *  The session-exit distill only learns AFTER a session ends; a turn that stalled
+ *  (consecutive-failure / cycle / repeat guard fired) is a dead end the *next turn
+ *  of the SAME session* should already avoid. This writes ONE FailedAttempt concept
+ *  immediately so the per-turn memory injection resurfaces it (priorityOrder puts a
+ *  query-relevant FailedAttempt first), closing the loop the user described: each
+ *  iteration gets sharper by building on accumulated failure knowledge. Confidence
+ *  is "medium" (not "high") so it never enters the always-injected "core" tier — it
+ *  only surfaces when the query actually hits it, and the richer session-exit distill
+ *  later consolidates or replaces it. Best-effort: a write failure is swallowed. */
+export async function recordFailedAttempt(
+  cwd: string,
+  attempt: { title: string; description?: string; body?: string; tags?: string[] },
+): Promise<{ recorded: boolean; skipped?: string }> {
+  if (jeoEnv("NO_MEMORY") === "1") return { recorded: false, skipped: "disabled (JEO_NO_MEMORY=1)" };
+  const title = attempt.title?.trim();
+  if (!title) return { recorded: false, skipped: "empty title" };
+  try {
+    const bundleDir = path.join(cwd, ".jeo", "memory");
+    // confidence "medium" keeps it out of the always-injected core tier (priorityOrder)
+    // — it only surfaces when the query actually hits it.
+    await upsertConceptFile(bundleDir, {
+      type: "FailedAttempt",
+      title,
+      description: attempt.description ?? "",
+      body: attempt.body ?? "",
+      tags: Array.isArray(attempt.tags) ? attempt.tags.filter(t => typeof t === "string") : [],
+      confidence: "medium",
+    });
+    await withIndexLock(bundleDir, async () => {
+      await rebuildIndex(bundleDir);
+      await updateLog(bundleDir, [{ title, type: "FailedAttempt" }]);
+    });
+    invalidateConceptCache();
+    return { recorded: true };
+  } catch (err: any) {
+    return { recorded: false, skipped: `record failed: ${err?.message ?? String(err)}` };
+  }
+}
+
 
 
 // ── Detached background distillation (round-16) ──

package/src/commands/deep-interview.ts

@@ -497,7 +497,9 @@ export async function runDeepInterviewEngine(opts: DeepInterviewEngineOptions =
           `  "constraints": ["Optional list of constraints once ambiguity is <= ${threshold}"],\n` +
           `  "acceptance_criteria": ["Concrete, testable acceptance criteria required before the seed can freeze"]\n` +
           `}\n` +
-          `Ensure ambiguityScore drops dynamically as more detail is gathered. Do not report ambiguityScore <= ${threshold} unless acceptance_criteria is populated with concrete, testable checks.`
+          `Ensure ambiguityScore drops dynamically as more detail is gathered. Do not report ambiguityScore <= ${threshold} unless acceptance_criteria is populated with concrete, testable checks.\n` +
+          `Do not fill an ambiguous point with your own convenient assumption to push the score down — surface that assumption as the nextQuestion instead. Never supply unstated detail that makes the request look simpler or safer than the user actually wrote it.\n` +
+          `Conversely, when the user's answers genuinely resolve a dimension, lower the score accordingly — do not keep a dimension ambiguous just to prolong the interview. If you notice yourself quietly narrowing the user's idea to make it easier to score, that narrowing is the signal the dimension is still open: ask, don't assume.`
       },
       {
         role: "user",

package/src/commands/launch.ts

@@ -4,7 +4,7 @@ import { PassThrough } from "node:stream";
 import { runAgentLoop, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, type AgentLoopEvents } from "../agent/engine";
 import { createOpikTracer, wrapEvents } from "../agent/opik-tracer";
 import { initialDynamicStepLimit } from "../agent/step-budget";
-import { memoryPromptSection, spawnDetachedDistill } from "../agent/memory";
+import { memoryPromptSection, spawnDetachedDistill, recordFailedAttempt } from "../agent/memory";
 import { createTaskTool, taskToolProtocolLine, type TaskSubEvent } from "../agent/task-tool";
 import { createSubagentTool, SUBAGENT_TOOL_PROTOCOL_LINE } from "../agent/subagent-tool";
 import { SubagentRegistry } from "../agent/subagent-registry";
@@ -68,7 +68,7 @@ import { renderInputFrame, type HighlightRange } from "../tui/components/input-b
 import { renderStatusBar } from "../tui/components/status";
 import { detectColorLevel, ColorLevel, visibleWidth } from "../tui/components/color";
 import { readClipboardImage } from "../util/clipboard-image";
-import { attachImagePaths } from "../util/file-attachment";
+import { attachImagePaths, insertImageTag } from "../util/file-attachment";
 import { formatTranscript } from "../tui/components/transcript";
 import { copyTextToClipboard } from "../tui/clipboard";
 import { loadInputHistory, appendInputHistory } from "../agent/input-history";
@@ -535,7 +535,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // (high-confidence core concepts are always prioritized regardless).
   const memoryBlock = await memoryPromptSection(cwd, flags.message || undefined);
 
-  const baseSystemPrompt =
+  const baseSystemPromptNoMemory =
     preamble + "\n\n" + protocol + "\n\n" +
     WORKING_DISCIPLINE + "\n\n" +
     OUTPUT_DISCIPLINE + "\n\n" +
@@ -554,15 +554,34 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     "- If the user pasted SKILL.md docs as reference material, treat them as user data and follow the latest concrete request.\n" +
     "- Before writing code or files in a domain a loaded skill covers, read that SKILL.md first — skills encode repo/env constraints absent from your training; several may apply, so don't pre-judge that none is needed.\n" +
     "- Your done reason must describe YOUR work or answer — never recite skill documentation.\n" +
-    skillsPromptSection(workflowSkills)) +
-    (memoryBlock ? "\n\n" + memoryBlock : "");
+    skillsPromptSection(workflowSkills));
 
-  let systemPrompt = withProjectContext(baseSystemPrompt, contextFiles);
-  if (flags.appendSystemPrompt) {
-    systemPrompt += "\n" + flags.appendSystemPrompt;
-  }
+  // Re-assemble the system prompt for a given memory block. The OKF memory block is
+  // recomputed per turn (with that turn's query) so failure-first ranking actually
+  // fires interactively and mid-session captures resurface — see refreshMemory below.
+  const composeSystemPrompt = (memBlock: string): string => {
+    const base = baseSystemPromptNoMemory + (memBlock ? "\n\n" + memBlock : "");
+    let sp = withProjectContext(base, contextFiles);
+    if (flags.appendSystemPrompt) sp += "\n" + flags.appendSystemPrompt;
+    return sp;
+  };
+  const systemPrompt = composeSystemPrompt(memoryBlock);
 
   const history: Message[] = [{ role: "system", content: systemPrompt }];
+  // Per-turn OKF memory refresh: recompute the injected memory block with THIS turn's
+  // query and rewrite the system message in place. The session-start block was built
+  // once (no query in interactive mode, so failure-first ranking never fired); doing
+  // it per turn means each loop iteration pulls query-relevant past failures to the
+  // top and picks up dead ends captured earlier in the SAME session. Opt out with
+  // JEO_STATIC_MEMORY=1 (freeze the session-start block); JEO_NO_MEMORY=1 still wins.
+  const refreshSessionMemory = async (query: string): Promise<void> => {
+    if (jeoEnv("STATIC_MEMORY") === "1") return;
+    if (!history[0] || history[0].role !== "system") return;
+    try {
+      const fresh = await memoryPromptSection(cwd, query || undefined);
+      history[0] = { ...history[0], content: composeSystemPrompt(fresh) };
+    } catch { /* keep the prior system prompt on any failure */ }
+  };
   let sessionModel: string | undefined = initialSessionModel;
   // Session thinking-level override (`/thinking`); falls back to the config level.
   let sessionThinking: "minimal" | "low" | "medium" | "high" | "xhigh" | undefined = flags.thinking ?? cfg.thinkingLevel;
@@ -764,6 +783,9 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         interactiveTurnActive = true;
         tui.start();
       }
+      // Refresh injected OKF memory with THIS turn's query before the model call so
+      // failure-first ranking fires and same-session dead ends resurface.
+      await refreshSessionMemory(userInput);
       const compRes = await maybeCompact(history, {
         model: activeModel,
         contextTokens,
@@ -1062,6 +1084,30 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       sessionUsage.outputTokens += result.usage.outputTokens;
     }
     sessionUsage.turns++;
+
+    // Mid-session failure capture: a guard-detected stall (the model repeated /
+    // cycled / consecutively failed without recovering) is a dead end the rest of
+    // THIS session should avoid. Record it into OKF now (deterministic, no LLM) so
+    // the next turn's memory refresh resurfaces it. Best-effort; never blocks the turn.
+    if (result.stopClass) {
+      const task = userInput.replace(/\s+/g, " ").trim();
+      const excerpt = task.length > 70 ? task.slice(0, 70) + "…" : task;
+      const why = result.stopClass === "consecutive_failure"
+        ? "consecutive failing tool calls"
+        : result.stopClass === "cycle"
+          ? "cycling through the same tool calls"
+          : "repeating the same tool call";
+      const tags = Array.from(new Set(
+        task.toLowerCase().match(/[a-z0-9][a-z0-9_-]{3,}/g) ?? [],
+      )).slice(0, 8);
+      void recordFailedAttempt(cwd, {
+        title: `Stalled on: ${excerpt}`,
+        description: `A prior turn stalled (${why}) on this task — change approach before retrying.`,
+        body: `Task: ${task.slice(0, 240)}\n\nThe agent gave up after ${why} (${result.steps} steps) and could not recover. ` +
+          `Do NOT repeat the same line of attack; try a different decomposition, tool, or verification path.`,
+        tags,
+      }).catch(() => {});
+    }
     const usage = result.usage ? `  (${result.usage.inputTokens} in / ${result.usage.outputTokens} out tokens)` : "";
 
     if (turnConfig.gitAutoCommit) {
@@ -2671,7 +2717,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
               if (dropped.images.length === 0 || dropped.text === before) return;
               pendingImages.push(...dropped.images);
               rli.line = dropped.text;
-              rli.cursor = dropped.text.length; // drop lands at the caret (line end in the common case)
+              rli.cursor = dropped.cursor; // park right after the swapped-in tag (whitespace normalized)
               typedLine = dropped.text;
               // Keep readline's internal screen model in step with the swapped-in tag so
               // the caret is not offset on the next keystroke (mirrors the Ctrl+V path).
@@ -2736,12 +2782,14 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             const img = await readClipboardImage();
             if (!img) return;
             pendingImages.push(img);
-            const tag = `[image #${pendingImages.length}]`;
             const rli = rl as unknown as { line: string; cursor: number; _refreshLine?: () => void };
             const at = typeof rli.cursor === "number" ? rli.cursor : rli.line.length;
-            const sep = rli.line.length > 0 && at > 0 && rli.line[at - 1] !== " " ? " " : "";
-            rli.line = rli.line.slice(0, at) + sep + tag + " " + rli.line.slice(at);
-            rli.cursor = at + sep.length + tag.length + 1;
+            // Insert the [image #N] tag at the caret with normalized single-space
+            // padding (shared with the drag-drop path) so the caret lands right after
+            // the tag instead of being pushed several columns by stray spaces.
+            const ins = insertImageTag(rli.line, at, pendingImages.length);
+            rli.line = ins.text;
+            rli.cursor = ins.cursor;
             typedLine = rli.line;
             // Sync readline's internal screen model to the injected tag (same as the
             // slash/tab completion accept paths): without it readline's stale row/cursor

package/src/commands/skills.ts

@@ -1,18 +1,9 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import * as os from "node:os";
-import { SKILLS, getSkillFrom, formatSkill, loadSkills, skillDirs, bundledSkillFileContent } from "../skills/catalog";
+import { SKILLS, getSkillFrom, formatSkill, loadSkills, skillDirs, bundledSkillFileContent, userSkillsDir } from "../skills/catalog";
 import { getLocalJeoDir } from "../agent/state";
-import { jeoEnv } from "../util/env";
-
-/** User-level bundled-skills install dir (`~/.jeo/skills`, honoring JEO_CONFIG_DIR /
- *  $HOME overrides) — the destination `jeo skills sync` reconciles against, matching
- *  the highest-precedence flat dir in {@link skillDirs}. */
-export function userSkillsDir(): string {
-  const userHome = process.env.HOME || os.homedir();
-  const home = jeoEnv("CONFIG_DIR") || path.join(userHome, ".jeo");
-  return path.join(home, "skills");
-}
+
+export { userSkillsDir };
 
 export type SkillSyncStatus = "missing" | "up-to-date" | "differs";
 export type SkillSyncAction = "installed" | "overwritten" | "preserved" | "unchanged" | "none";

package/src/prompts/agents/architect.md

@@ -11,6 +11,7 @@ Assess architecture, maintainability, correctness, and spec compliance with file
 - Prioritize spec/root-cause correctness before style comments.
 - Rate findings by severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`.
 - Never return `APPROVE` if CRITICAL/HIGH issues remain.
+- A clean verdict is not the absence of inspection: do not return `CLEAR`/`APPROVE` merely because no problem surfaced. Base the verdict on files and paths you concretely examined, and say which ones.
 </constraints>
 
 <execution_loop>
@@ -29,6 +30,7 @@ Assess architecture, maintainability, correctness, and spec compliance with file
 Your final `done.reason` MUST be markdown with these sections:
 - `Summary:`
 - `Findings:`
+- `Inspected:` the files/paths you actually examined (evidence for the verdict)
 - `Recommendations:`
 - `Architectural Status:` one of `CLEAR`, `WATCH`, `BLOCK`
 - `Code Review Recommendation:` one of `APPROVE`, `COMMENT`, `REQUEST CHANGES`

package/src/prompts/agents/critic.md

@@ -10,6 +10,7 @@ Decide whether a plan or approach is actionable before execution proceeds.
 - Read-only: never modify files.
 - Do not invent problems; reject only with concrete gaps.
 - Simulate representative tasks against inspected evidence before deciding.
+- Honesty cuts both ways: if you catch yourself softening a real, blocking gap into `[ITERATE]` just to avoid blocking, that softening is the signal the gap is real — name it. But never manufacture a block: when gaps are concrete yet fixable in-flight prefer `[ITERATE]` over `[REJECT]`, and return `[OKAY]` once the plan is genuinely actionable.
 </constraints>
 
 <execution_loop>

package/src/skills/catalog.ts

@@ -261,6 +261,15 @@ export function skillSlashAliases(skill: SkillDoc): string[] {
 }
 
 
+/** User-level bundled-skills install dir (`<config>/skills`, i.e. `~/.jeo/skills`
+ *  honoring JEO_CONFIG_DIR / $HOME) — the highest-precedence flat skill dir and the
+ *  destination `jeo skills sync` reconciles against. $HOME wins over os.homedir() so
+ *  tests/sandboxes that re-point HOME are honored (see {@link skillDirs}). */
+export function userSkillsDir(): string {
+  const userHome = process.env.HOME || os.homedir();
+  return path.join(jeoEnv("CONFIG_DIR") || path.join(userHome, ".jeo"), "skills");
+}
+
 /** Global + per-project skill-doc directories (user-configurable SKILL.md files).
  *  Ordered lowest → highest precedence (a later dir's skill overrides an earlier
  *  one with the same name): foreign-ecosystem roots first, jeo-native last.
@@ -283,7 +292,7 @@ export function skillDirs(cwd: string = process.cwd()): string[] {
     path.join(userHome, ".claude", "skills"),
     path.join(home, "agent", "skills"),
     path.join(userHome, ".agents", "skills"),
-    path.join(home, "skills"),
+    userSkillsDir(),
     path.join(cwd, ".claude", "skills"),
     path.join(cwd, ".agents", "skills"),
     path.join(cwd, ".jeo", "skills"),

package/src/util/file-attachment.ts

@@ -18,6 +18,54 @@ import type { ImageAttachment } from "../ai/types";
 
 const IMAGE_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp)$/i;
 
+
+/**
+ * Normalize the whitespace around every `[image #N]` tag to a single space:
+ *  - one space before a tag that follows other text (none at line start),
+ *  - one space after a tag that is followed by more text,
+ *  - any run of spaces/tabs collapsed to one, and the whole string trimmed.
+ *
+ * A tag at the very end keeps NO trailing space (callers that want the caret to sit
+ * past it add exactly one). Terminals pad a dragged-and-dropped path with their own
+ * spacing and the Ctrl+V insert adds a separator, so without this the caret parks
+ * several columns past the tag — the "input point looks pushed by a few spaces" bug.
+ * Idempotent: re-normalizing already-clean text is a no-op.
+ */
+export function normalizeImageTags(text: string): string {
+  return text
+    .replace(/[ \t]*(\[image #\d+\])[ \t]*/g, (m, tag: string, off: number, s: string) =>
+      (off > 0 ? " " : "") + tag + (off + m.length < s.length ? " " : ""),
+    )
+    .replace(/[ \t]{2,}/g, " ")
+    .trim();
+}
+
+/** Caret offset just past the `[image #n]` tag in `text` (and its single trailing
+ *  space when present); falls back to end-of-text when the tag is absent. */
+export function caretAfterTag(text: string, n: number): number {
+  const tag = `[image #${n}]`;
+  const idx = text.indexOf(tag);
+  if (idx < 0) return text.length;
+  let end = idx + tag.length;
+  if (text[end] === " ") end += 1; // sit after the separating space, not on it
+  return end;
+}
+
+/**
+ * Insert an `[image #n]` tag at `cursor` within `line` (the Ctrl+V clipboard-image
+ * path), normalizing surrounding whitespace so the tag is flanked by exactly one
+ * space. A tag landing at end-of-line gets one trailing space so the user can keep
+ * typing; the returned caret sits right after the tag (and that space).
+ */
+export function insertImageTag(line: string, cursor: number, n: number): { text: string; cursor: number } {
+  const at = Math.max(0, Math.min(cursor, line.length));
+  const tag = `[image #${n}]`;
+  let text = normalizeImageTags(line.slice(0, at) + tag + line.slice(at));
+  const idx = text.indexOf(tag);
+  if (idx >= 0 && idx + tag.length >= text.length) text += " "; // trailing space at EOL for typing
+  return { text, cursor: caretAfterTag(text, n) };
+}
+
 /** Detect an image media type from magic bytes, or null when the bytes are not a
  *  recognised image. Used as the authoritative check (extension only gates the
  *  candidate scan; the bytes decide). */
@@ -114,6 +162,10 @@ export interface AttachResult {
   text: string;
   /** The newly-read image attachments, in source order. */
   images: ImageAttachment[];
+  /** Caret offset to park after the swap: just past the trailing space of the LAST
+   *  inserted tag (so the live box places the cursor right after the attachment,
+   *  ready for the user's prompt). Equals `text.length` when nothing was attached. */
+  cursor: number;
 }
 
 /**
@@ -131,7 +183,7 @@ export async function attachImagePaths(
   read: FileReader = defaultReader,
 ): Promise<AttachResult> {
   const tokens = findImagePathTokens(text);
-  if (tokens.length === 0) return { text, images: [] };
+  if (tokens.length === 0) return { text, images: [], cursor: text.length };
 
   const reads = await Promise.all(
     tokens.map(async (t) => {
@@ -154,5 +206,9 @@ export async function attachImagePaths(
     n += 1;
   }
   out += text.slice(cursor);
-  return { text: out, images };
+  if (images.length === 0) return { text: out, images, cursor: out.length };
+  // Collapse the spacing terminals add around a dropped path so the swapped-in tag
+  // (and the caret parked after it) is not pushed several columns to the right.
+  const normalized = normalizeImageTags(out);
+  return { text: normalized, images, cursor: caretAfterTag(normalized, n - 1) };
 }