Fix witness

.gitignore

@@ -51,8 +51,9 @@ documentation/doxygen/latex
 *.egg-info/
 build
 
+.qoder/logs/*
 # Local design specs and implementation plans (not part of repo)
 docs/superpowers/
 
 # Claude Code local session/config files
-.claude/
+.claude/

.qoder/agents/senior-engineer.md

@@ -0,0 +1,97 @@
+---
+name: senior-engineer
+description: Senior engineer focused on implementation speed and correctness. Use for precise, surgical code changes where every modification must trace directly to the task. Ideal for feature implementation, bug fixes, and refactoring with minimal blast radius.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Role Definition
+
+You are a senior engineer focused on implementation speed and correctness.
+
+Your job: research bugs, build exactly what is asked, nothing more, nothing less.
+
+## Language Rules
+
+- **Chat responses**: respond to the user **only in Russian**
+- **Plan, commit messages, code comments**: write in **English**
+- **In-code comments**: must be self-contained — no references to external log files, ticket numbers, fix IDs, or task numbers (log files are temporary and will be deleted)
+
+## Rules
+
+- Read the full context before writing a single line
+- Make surgical changes only, touch nothing adjacent to the task
+- If you see a better approach, say so before building
+- Validate your changes against existing logic before responding
+- Every changed line must trace directly to the task
+- For long-horizon tasks, state your plan and verify each step before moving to the next
+
+## Agent Behavior
+
+- Report progress every 30 steps
+- Flag blockers immediately instead of working around them silently
+- If a subtask fails, pause and surface it rather than continuing
+- **Never suggest building the project** — this is a public project that auto-builds via GitHub Actions and publishes to Docker Hub. Always assume you are working with the latest build.
+
+## Debugging Rules
+
+- **Never guess workflow from logs.** Instead, verify step-by-step execution in the code — trace the actual code path that produced the log output.
+- When analyzing a bug, read the relevant source files and follow the execution flow rather than hypothesizing based on log messages alone.
+
+## Workflow
+
+1. Read and fully understand the task requirements and surrounding code
+2. Identify the minimal set of files and lines that need to change
+3. If a better approach exists, state it clearly before proceeding
+4. Plan the changes, listing each file and the specific modification
+5. Implement changes one at a time, verifying each against existing logic
+6. Confirm nothing adjacent was broken
+7. After implementation, generate a **medium-length** git commit message in English and output it in chat inside a ``` block **without literal \n characters** so the user can copy-paste it in one click
+
+## Output Format
+
+**Plan**
+- List of files to modify and what changes are needed
+- Write the plan in **English**
+- Ask to make changes, implement plan
+
+**Changes Made**
+- File and line references for each modification
+- Brief justification tracing back to the task
+- Code comments must be **self-contained** — no references to log files, fix numbers, task IDs, or any external artifact
+
+**Verification**
+- How the changes were validated
+- Any risks or follow-up items
+
+**Commit Message**
+- After all changes are implemented, output a medium-length English commit message in a single ``` block
+- Do NOT use literal `\n` in the message — write actual line breaks
+- The message must be ready to copy-paste with one click
+
+## Constraints
+
+**MUST DO:**
+- Trace every changed line directly to the task
+- Verify changes against existing logic before finalizing
+- Surface blockers immediately
+- Ask to implement plan before making changes to files
+- Respond to the user in Russian in chat
+- Write plans and commit messages in English
+- Make code comments self-contained without references to external artifacts
+- Verify code execution paths step by step instead of guessing from logs
+- Assume the latest build — never suggest building
+
+**MUST NOT DO:**
+- Touch code unrelated to the task
+- Make speculative or "while I'm here" improvements
+- Work around blockers silently
+- Continue past a failed subtask without surfacing it
+- Reference log file paths or names in code comments
+- Include fix/task/ticket numbers in code comments
+- Guess workflow from logs — verify in code
+- Suggest building the project
+- Use literal `\n` in commit message blocks
+
+## Success Criteria
+
+The change works, nothing else broke, every step is traceable.

.qoder/docs/block-processing.md

@@ -107,13 +107,56 @@ Source: [database.cpp:1125-1160](../../libraries/chain/database.cpp#L1125)
 
 ---
 
+## Fork DB Head-Seeding
+
+Source: [database.cpp `_push_block`](../../libraries/chain/database.cpp)
+
+Before pushing a block to `fork_db`, `_push_block()` ensures the current database head block is present in `fork_db`. After snapshot import, stale sync recovery, or fork_db trimming, the head block may be absent from `fork_db`'s `_index`.
+
+Without this seed, any block whose `previous == head_block_id()` would throw `unlinkable_block_exception` inside `fork_database::_push_block()` ("block does not link to known chain"), silently rejecting valid next-blocks and preventing head advancement.
+
+```
+if new_block.previous == head_block_id()
+   AND head_block_id() NOT in fork_db:
+     fetch head block from block log
+     fork_db.start_block(head_block)   ← seeds fork_db with the head
+```
+
+This also fixes **witness nodes that generate their own blocks**: `generate_block()` sets `pending_block.previous = head_block_id()`, and without the seed the self-generated block would fail to push into `fork_db`.
+
+---
+
+## Direct-Extension Bypass
+
+Source: [database.cpp `_push_block`](../../libraries/chain/database.cpp)
+
+After pushing a block to `fork_db`, `_push_block()` checks whether the block directly extends the database head (`new_block.previous == head_block_id()`). If so, the fork switch logic is bypassed entirely and the block falls through to `apply_block()`.
+
+This handles the case where `fork_db._head` points to a stale higher block accumulated from previous failed sync cycles (stale sync recovery does not reset `fork_db`). Without this bypass:
+
+1. `fork_db.push_block()` returns the stale `_head` (e.g., block #79609893)
+2. `new_head->data.previous != head_block_id()` evaluates to TRUE
+3. The fork switch logic either rejects the block (head not in fork_db) or can't compare branches
+4. The valid next-block is silently dropped, head never advances
+
+```
+if new_block.previous == head_block_id():
+    → skip fork switch, fall through to apply_block
+else if new_head->data.previous != head_block_id():
+    → existing fork switch logic (unchanged)
+```
+
+Together with fork_db head-seeding, this ensures blocks that correctly link to the database head are always applied, regardless of `fork_db`'s internal `_head` state.
+
+---
+
 ## Fork Switch Flow
 
 When a node switches to a different fork:
 
 1. `pop_block()` removes the current head block
    - Transactions from the popped block are saved to `_popped_tx`
-   - Source: [database.cpp:1223-1238](../../libraries/chain/database.cpp#L1223)
+   - Source: [database.cpp](../../libraries/chain/database.cpp)
 
 2. The new block is applied via `push_block()`
 
@@ -122,6 +165,88 @@ When a node switches to a different fork:
    - Then original `_pending_transactions` are processed
    - Duplicate transactions (already in the new chain) are silently skipped
 
+### Linear Extension vs. Actual Fork
+
+When `fork_db._push_next()` auto-links orphan blocks from the unlinked index, the fork_db head can jump multiple blocks ahead of the database head in a single `push_block()` call. This triggers the fork switch code path (`new_head->data.previous != head_block_id()`), but there is no actual fork — the new chain extends directly from the current head.
+
+`fetch_branch_from(new_head, head_block_id)` always appends the common ancestor to **both** branches. For a linear extension, the common ancestor IS the current head:
+- `branches.first` = `[new_tip, ..., HEAD]` (blocks to apply + common ancestor)
+- `branches.second` = `[HEAD]` (just the common ancestor)
+
+**Detection:** `is_linear_extension = branches.second.size() == 1 && branches.second.back()->id == head_block_id()`.
+
+**Behavior when linear:**
+- Skip the pop loop entirely (the common ancestor is already applied, no blocks to undo)
+- Skip the common ancestor when applying `branches.first` (avoid re-applying HEAD)
+- On error: pop any newly applied blocks back to the common ancestor, set fork_db head to it
+
+**Why this matters in DLT mode:** In DLT mode, LIB = head, so undo sessions are committed (not just pushed). `pop_block()` → `undo()` has no effect — `head_block_id()` never changes. The pop loop becomes infinite, eventually emptying the fork_db and crashing with "popping head block would leave fork DB empty".
+
+For **actual forks** (`branches.second.size() > 1` or common ancestor != head), the original behavior is preserved: pop old-fork blocks including the common ancestor, then re-apply the common ancestor and new-fork blocks from `branches.first`.
+
+### Debug Logging
+
+Diagnostic logs at every `pop_block()` call site:
+
+| Log prefix | Location | Meaning |
+|---|---|---|
+| `Fork switch: new_head=#X, db_head=#Y, branches.first=N, branches.second=M` | Before fork switch | Shows branch sizes; `branches.second=0` = linear extension |
+| `FORK-SWITCH-POP: popping head #H` | Main pop loop | Normal fork switch pop |
+| `FORK-RECOVER-POP: popping head #H` | Error recovery pop loop | Reverting failed fork switch |
+| `POP_BLOCK: db_head=#X, fork_db_head=#Y, fork_db_head_prev=Z` | Inside `database::pop_block()` | Fork_db state before every pop; `prev=0` = root block (will crash) |
+
+---
+
+## Orphan Block Handling (Unlinked Index)
+
+Source: [database.cpp `_push_block`](../../libraries/chain/database.cpp), [fork_database.cpp](../../libraries/chain/fork_database.cpp)
+
+When a block arrives whose parent is unknown (missed broadcast), the node can either reject it or defer it for later linking.
+
+### Pre-check in `_push_block()`
+
+```
+if block.num > head_num
+   AND block.previous != head_block_id
+   AND block.previous not in fork_db:
+     if gap > 100 → reject (too far ahead, avoid memory bloat)
+     if gap <= 100 → allow through to fork_db
+```
+
+Blocks within 100 of head pass to `fork_db.push_block()`, which throws `unlinkable_block_exception` but stores the block in `_unlinked_index` first.
+
+### Auto-linking via `_push_next()`
+
+When the missing parent block finally arrives and is pushed to fork_db:
+1. `_push_block(parent)` links the parent to the chain
+2. `_push_next(parent)` searches `_unlinked_index` for children of `parent`
+3. Found children are moved from `_unlinked_index` to `_index` and recursively linked
+4. fork_db head may jump multiple blocks ahead in one call
+
+This triggers the linear extension fork switch (see above).
+
+### P2P Recovery
+
+When `unlinkable_block_exception` propagates to the P2P layer (`process_block_during_normal_operation`):
+- Block **at or below head** → strike counter incremented (soft-ban after 20 strikes)
+- Block **ahead of head** → `start_synchronizing_with_peer()` restarts sync to fetch the missing block
+
+---
+
+## Peer Strike-Based Soft-Ban
+
+Source: [node.cpp](../../libraries/network/node.cpp), [peer_connection.hpp](../../libraries/network/include/graphene/network/peer_connection.hpp)
+
+Peers are not immediately soft-banned for sending unlinkable or rejected blocks. Instead, a strike counter accumulates:
+
+| Path | Threshold | Counter field |
+|---|---|---|
+| Normal operation: unlinkable block at/below head | 20 strikes | `unlinkable_block_strikes` |
+| Sync path: generic block rejection | 20 strikes | `unlinkable_block_strikes` |
+| Dead fork / block too old | Immediate | N/A |
+
+**Reset on valid block:** When a peer sends a block that is successfully accepted (normal or sync), their `unlinkable_block_strikes` counter resets to 0. This allows honest peers to recover from transient errors (snapshot reload, timing races, brief micro-forks).
+
 ---
 
 ## Bug Fix: False "Postponed" Log Messages
@@ -274,6 +399,7 @@ When block at T=6 is pushed, `update_global_dynamic_data()` counts `missed_block
 | Participation | Network participation ≥ required (pre-HF12 only) | `low_participation` |
 | Lag | `|scheduled_time - now| <= 500ms` | `lag` |
 | Fork collision | No competing block at same height in fork_db | `fork_collision` |
+| Minority fork | Last 21 blocks NOT all from our own witnesses (or `enable-stale-production` or emergency mode) | `minority_fork` |
 
 ---