Skip to content

Runbook: rebase ht onto upstream/master (parked 2026-05-12) #38

@marksverdhei

Description

@marksverdhei

Status

Parked mid-integration on 2026-05-12. Owner: @marksverdhei to schedule completion.

The mechanical CI restoration (auth + master reset) is complete or in progress separately. This issue tracks the full rebase of ht onto current upstream/master which is a multi-hour subsystem migration, not a routine sync.

The daily cron, once authentication is restored, will rebase-fail and the workflow's existing-issue check should route its automatic comments here rather than create duplicates.

State of the world at park time

  • origin/master ✓ reset to upstream/master (89730c8), backup tag master-pre-reset-20260512-155945 → old polluted state (5fc05ff) on origin for rollback
  • origin/ht ✓ untouched at 5be5481f9 (the titan-deployed working state), backup tag ht-pre-rebase-20260512 → same SHA
  • Local merge work staged in worktree /tmp/ht-rebase-preview branch ht-merged (ephemeral — see Archival below)
  • All 49 merge conflicts resolved with feature-preservation audit passing
  • Pre-commit hook (npm run check) blocks the commit with 148 TypeScript errors — structural integration drift from upstream's Spring Cleaning Refactor (webui: Spring Cleaning Refactor v1 ggml-org/llama.cpp#22505)

Feature-preservation audit baseline

Recorded so the next attempt can verify no silent feature drops:

# Subsystem Identifier regex Min hits on origin/ht
1 LoRA common_lora_adapter_info|name_meta|version_meta|discovered_adapters|get_discovered_adapters|gguf_is_lora_adapter|lora-init-without-apply 41
2 TurboQuant tbq3_0|tbq4_0|TBQ3_0|TBQ4_0|TURBOQ|GGML_TYPE_TBQ|ggml-turboq 265
3 Transparency cards ChatMessageSystem|ChatMessageTool|showSystemMessage|alwaysShowAgenticTurns|showToolMessagesAsStandalone|MessageRole\.TOOL 86
4 Tools menu compose_collage|search_images|search_news|fetch_url|fetch_image|web_search 103
5 Terminal sandbox-terminal|send_keys|WS reconnect|TerminalSession|termd 150
6 Image pipeline ComfyUI|/v1/images|image-artifact|markdown-image|wrap-images-as-artifacts 43
7 Tauri shell webkit2gtk|WEBKIT_DISABLE_DMABUF_RENDERER|software video decode|tauri\.allowlist 36
8 Branding ht-llama\.cpp|TurquoiseHue|PurplePalette|ht-fork|Heiervang 55
9 Settings AiCommandsEditor|NextcloudConnectionPanel|ThemeHuePicker|TtsRefAudioPicker 19
10 Routing /lora-adapters|/cors-proxy|/comfyui-proxy 25

The completed merge attempt verified all 10 subsystems at exact parity (sometimes higher counts because upstream-touched files were already merged). Audit gate one-liner is on the parked patch.

Discoveries to carry forward (do not re-derive)

  1. Soft-reset squash is wrong for this fork. Tree-identity preserves HT but erases upstream's 163 commits worth of improvements over the ~632 upstream-only-touched files. Confirmed by directional analysis. Use merge + linearize instead.
  2. git rerere is unsafe on long-lived divergence. Cached resolutions from prior exploratory merges (May 3) silently dropped the LoRA dedupe block in tools/server/server-models.cpp during a fresh merge of origin/ht. Caught by spot-check, not by tooling. Standing rule: rerere.enabled = false on this fork; archived cache at .git/rr-cache.bak.20260512 if forensic review is wanted.
  3. favicon.ts is a DU file: upstream's e3e3f8e46 "Remove Google Favicons" deletes it; tools/server/webui/src/lib/services/mcp.svelte.ts still imports getFaviconUrl from it. Restored from origin/ht during conflict resolution.
  4. Settings registry is NOT a simple unification. Upstream introduced a complete new settings-registry.ts with SETTINGS_SECTION_TITLES (8 entries), SETTINGS_SECTION_SLUGS, section data structures, and field bindings. HT's settings-sections.ts (12 entries) is the data that needs migrating into upstream's structure — Cat 3 pattern, not Cat 2. ~2-4h of focused work on its own.
  5. Context/component renames change shape, not just name. getChatSettingsDialogContextgetChatSettingsConfigContext is a structural change; calling code that did .open() on the old context fails on the new one. Each rename site needs adaptation, not just renaming.
  6. DU-files-took-ht-side strategy means probable build-time import errors. Expected during merge resolution; address in the integration phase, not the merge phase.

Resolution categories from the 49-file conflict surface

Generated artifacts (4): tools/server/public/{bundle.css,bundle.js,index.html}, tools/server/webui/package-lock.json — take ht, regenerate at end via npm install + npm run build.

GGML (1): ggml/src/ggml-cpu/arch-fallback.h — take upstream.

READMEs (3): tools/{cli,completion,server}/README.md — take upstream, regenerate via llama-gen-docs post-merge. Validation gate: confirm CLI parser still understands HT-specific values (e.g. tbq3_0, tbq4_0) before regenerating; otherwise doc regen consolidates a silent revert.

DU files (11): upstream-deleted, ht still uses — take ht, expect import errors to fix later.

UA files (6): ht-only additions — take ht.

Both-touched conflict resolutions (24+): per-file domain judgment. Heaviest in tools/server/webui/src/lib/** (Svelte sources for Spring Cleaning Refactor conflicts). The full per-file resolution log is in the patch archive (see Archival).

Realistic estimate to completion

8-15h focused integration work on top of the resolved merge:

  • Settings registry unification (port HT's 4 extra sections into upstream's pattern): 3-5h
  • Context/component rename adjustments (shape-change, not just rename): 1-2h
  • Route-path updates (/chat/[id]/(chat)/chat/[id]): 30min
  • Implicit-any + remaining type mismatches: 1-2h
  • npm run build + smoke test on Tauri shell + titan regression: 1-2h
  • Audit gate re-verification: 30min
  • Linearize via read-tree + push to origin/ht: 30min

Original "get CI working" estimate was 1h. Actual rebase scope was systematically underestimated; this issue captures the truth so the next attempt budgets correctly.

Archival

Work-in-progress patch saved to ~/ht/forks/parked-work/llamacpp-merge-wip*.patch (host-local).

If Markus authorizes a --no-verify archeology branch push for forensic preservation: branch will be named archeology/ht-merge-wip-20260512 on origin. Otherwise the local patch is the canonical artifact.

Resume protocol

  1. Restore the merge state: cd <ht-llama.cpp> && git checkout upstream/master -B ht-merged && git apply ~/ht/forks/parked-work/llamacpp-merge-wip*.patch
  2. Run the audit baseline grep on ht-merged HEAD — confirm parity vs origin/ht for all 10 subsystems before continuing.
  3. Tackle integration in this order: settings registry → context renames → route paths → implicit-any tail.
  4. After all 148 errors clear: npm run build, smoke, titan regression.
  5. Linearize: git checkout -b ht-linear upstream/master; git checkout ht-merged -- .; git commit -m "...".
  6. Markus approval → force-push origin/ht.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    sync-conflictUpstream sync rebase conflict

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions