Skip to content

Fork vs upstream nightly: what differs, and how to move fork features closer to upstream #416

Closed
1 of 1 issue completed

Description

@tannerpolley

Owner request (2026-11-16)

I want to know what the biggest difference is between my fork and upstream nightly most up to date release and what is actually different and if the way this fork is managed is the best way to add the custom features that I have (project view and issues are the biggest but there are others). I want to see how I can get it closer to upstream or if we can take what may already be present in upstream and convert our features to how they have set it up now.

Starting facts (2026-11-16)

Questions to answer

  1. Inventory: what the fork adds or changes compared with the latest nightly, grouped by feature. Examples: project view, issues/orchestration (issue queue, managed workers, repository orchestrator, model roles), MCP tools, usage bars, Writer role, PDF comments, and anything else found. For each: size (files/lines), where it hooks into upstream code (new modules vs edits inside upstream files), and how much merge conflict it causes.
  2. Overlap: for each fork feature, whether upstream nightly now has the same or a similar feature, or the building blocks for it. Examples: upstream issues/linear/GitHub integration, project views, subagents/delegation, task boards, extension or plugin points. Cite upstream files and PRs.
  3. Fork management: whether the current approach is the best way to carry these features. It is: one long-lived main, periodic upstream merges, and fork code mixed into upstream files. Compare it with alternatives such as rebasing onto upstream, isolating features behind seams or packages, contributing pieces upstream, or adopting upstream equivalents. Measure the cost of the last few syncs from git history.
  4. Recommendation: a ranked plan to move closer to upstream. Name which features to convert to upstream's model, which to keep but move behind seams, which to drop or send upstream, and what each costs. List the decisions the owner must make.

Constraints

  • Research only. No code changes, no pushes, and no upstream PRs.
  • Write findings and the plan on this issue.
  • Mobile is out of scope. Only Codex and Claude matter.

Activity

  1. tannerpolley commented on Nov 16, 2026

    @tannerpolley
    OwnerAuthor

    Designer findings: keep the fork, shrink its shared-file edits

    The two largest custom features still justify a fork. Project view overlaps partially with upstream; managed issues/repository orchestration does not have an upstream product equivalent in this nightly. The best path is to retain one main branch and real upstream merges, adopt upstream execution and presentation primitives, and isolate the remaining policy. Rebasing 898 fork-only commits would change the maintenance method without removing the underlying coupling.

    Research only, pinned to:

    • Fork main: d9c88282ab27d7e0bfa4d9fb1a9d68096c2e77ec.
    • Nightly v0.1.10-nightly.20261116.4800: 7d32075e3757ded707914e2450c3e392a9665765.
    • Merge base: 40526f96f6ae3dfe74ae60ca279e748d7838a691.

    1. What the numbers mean

    The issue's counts reproduce exactly: 898 fork-only / 1,419 upstream-only commits. Base → fork: 1,167 paths, +160,832/−4,998 lines. Base → nightly: 2,637 paths, +204,330/−64,139. Direct nightly → fork: 3,413 paths, +224,143/−208,500, but that mixes missing upstream changes with custom work and is unsuitable as a “custom code” estimate.

    The fork addition count includes 84,902 lines in 406 paths whose names contain test/fixture/snapshot. It is not 160k lines of production feature code. File-path intersection finds 390 paths changed on both sides. This is exposure to integration work, not a count of textual conflicts.

    Re-running git diff --dirstat=lines,2,cumulative BASE main gives orchestration-v2 24.9%, issues 15.7%, MCP 6.9%, web chat 4.7%, issues UI 5.7%, sidebar 4.3%. These are cumulative line-distribution figures including tests; the issue's earlier 12% orchestration figure is not reproduced with these flags.

    The following footprint buckets are reproducible filename/path classifications of base → fork numstat, including tests. They are not removal estimates. Classification order is issues/owner decisions → notebooks → PDF/annotations/artifacts → sidebar/project sections → usage/reset credits → explicitly named roles/Writer → remaining orchestration → remaining MCP → remaining contracts/client state → other. Shared integration edits therefore often appear in the later buckets.

    Footprint Paths + / − lines New paths vs base Paths also changed upstream
    Issues, issue work, owner decisions 169 46,233 / 0 169 0
    Remaining orchestration 129 34,517 / 1,468 58 58
    Project/sidebar organization 76 12,964 / 228 64 10
    Remaining MCP 44 10,065 / 272 14 26
    Notebook execution 27 6,254 / 73 26 1
    Usage and reset credits 57 5,330 / 58 29 17
    PDF/annotations/project artifacts 19 2,672 / 65 15 4
    Explicitly named roles/Writer files 9 891 / 0 9 0
    Remaining contracts/client state 89 5,589 / 268 26 49
    Other UI, providers, storage, tools, docs, assets 518 36,317 / 2,566 188 225

    Zero overlap for issue-owned paths does not mean issue work is conflict-free: its hooks live in Orchestrator, projections, launch, contracts, MCP, settings and the chat shell.

    2. Feature inventory and upstream overlap

    Project view — keep its unique organization; convert its shared foundations. The fork adds custom sections/subsections, placement and dragging, separate expansion/filter state, worker visibility, and repository-orchestrator actions. SidebarProjectSections is 1,797 added lines; Sidebar.tsx has 366 changed lines in the base comparison, with additional state/contracts/layout-service hooks. Risk is medium-high at the shell and shared thread rows, lower in section-owned files.

    Upstream already has project folders in its “boring” sidebar, keyboard tree behavior, grouped remote/local projects, pin/archive, and persisted folder expansion: Sidebar.tsx, SidebarProjectFolderHeader, sidebarProjectGrouping, PR #21039, PR #26154. These capabilities largely predate the merge base; they are existing building blocks, not all new discoveries since November 12. Upstream's folder mode has no custom nested sections and disables drag/Working shelf in that mode. Its project route redirects to project settings, not a new project dashboard. Replacing the whole fork view with upstream would remove requirements from #1/#2. Reuse upstream project identities, pin/archive mutations, row behavior and folder primitives where their semantics fit; retain section layout and owner-specific worker affordances in one feature component.

    Issues and repository orchestration — retain the domain, reduce runtime ownership. The fork adds an issue browser/detail view, milestone/roadmap grouping, links, inbox, queue, owner decisions, issue-change proposals, admission and attempt state, root ownership and handoffs, and GitHub/Forgejo/GitLab/git-bug adapters. Evidence: IssueWorkService, IssueService, RepositoryWorkCommands, IssueBrowser, ForkWsRpc. Issue-owned code is additive; ownership/lifecycle integration is the highest-risk part.

    I found no first-class issue board, Linear issue integration, issue admission queue or repository-orchestrator replacement in the tagged application source/contracts/toolkits. GitHub issue templates, repository moderation automation and triage that helps file a bug are not that product. Upstream does have source-control/PR services and PR link/watch tools; use those for PR facts and completion signals rather than duplicating them. This is a source inspection conclusion, not a claim about every external plugin a user could install.

    Delegation, model roles and Writer — strong execution overlap, custom policy remains. Upstream already supplies delegate_task, shared/worktree isolation, explicit provider/model/options, cancellation, result delivery, questions, scheduled tasks, native subagent projection and remote delegation. See tool definitions and delegate contract. It even has task roles: implementation, research, review, design, test and general. It does not have the fork's configured ordered model-role choices, weekly-headroom ranking, managed issue requirement, or Writer owner-routing policy.

    The fork's delegateTaskTarget adds 312 lines and demotes choices below 0.8 weekly headroom; threadRole, ModelRolesSettings, and ForkSettings own additional policy. Writer is more than a label: DelegatedRequestRouting and DelegatedTaskQuestionReactor keep its questions with the owner, backed by the Writer case in DelegatedCompletionDelivery.fork.test. Preserve that behavior while mapping custom roles into upstream target/isolation inputs. Do not replace managed issue attempts with provider-native subagents; native children do not supply repository ownership or issue admission.

    Upstream continues fixing this exact execution layer: #34551 selective task reads, #34620 queued-message versus completion ordering, #37399 parent-run-specific wakes, #37738 stopped Codex children. Those references come from commits contained in the pinned tag. Retaining a parallel lifecycle implementation increases the chance of missing these repairs.

    MCP — extend upstream, not a separate tool platform. Upstream already owns project/thread lifecycle, delegation, scheduling, browser/device, HTML and PR toolkits. Fork-specific issues, repository administration, notebooks and project artifacts need their own toolkits and service methods. Existing ForkWsRpc and ForkMigrations are good boundaries to retain. The remaining MCP bucket includes 482 changed lines in shared OrchestratorMcpService. Separate tool registration and role/admission policy from common task mechanics. Provider plugins/skills and MCP apps are real extension mechanisms, but the inspected code does not establish a general plugin API for adding native sidebar sections, transactional orchestration events and database projections. A wholesale “make this a plugin” proposal would require new architecture.

    Usage bars — substantial upstream coverage; retain only policy and presentation differences. Upstream already has UsageLimitsPooled, UsageLimitSources, Codex/Claude usage readers, and usage-limit recovery. Fork changes add pace/headroom behavior, model-selection policy, Claude reset-credit expiry/reminders/auto-use, and UI refinements. Preserve provider readings and limit normalization upstream; keep optional fork policy as a consumer. Do not assume a quota display means auto-use or switching behavior is equivalent. Risk is medium in display code, high where policy starts/restarts work.

    PDF comments, artifacts and notebooks — keep focused extensions over upstream viewers. Upstream PdfViewer supplies rendering/find/navigation; the fork adds text/area review comments delivered to the composer. PdfComments is 453 added lines plus a 47-line test; fork edits to PdfViewer are +177/−65. Keep the annotation overlay and review payload, adopt upstream viewer fixes such as #37064. Upstream NotebookPreview renders saved notebooks; fork NotebookService supplies Jupyter execution/edit/save/session handling. Preview is not execution. Project artifact persistence/sections/descriptions in ProjectArtifacts are not equivalent to upstream Codex artifact templates. These mostly owned modules have lower textual conflict exposure; keep security, execution ownership and save semantics.

    Other differences worth retaining or auditing individually. Additional overlapping path slices, not additive to the table above:

    • Inline shells/process inspection/background output: 16 paths, +3,426/−0 (InlineShell*, threadProcesses, ProcessProgram*, backgroundTaskOutput, BackgroundTask*). Upstream terminals/background work are foundations; the fork adds controls and detailed output, so no blanket deletion.
    • Persistence/storage/observability/history: 61 paths, +4,098/−420. Shared storageCleanup.ts alone changes 985 lines; this is a major sync seam, not merely housekeeping.
    • Desktop: 29 paths, +2,530/−143, including fork update/shutdown behavior and tests.
    • Git/worktree-related paths: 23, +1,249/−144, including fork placement and workflow handling.
    • Settings/skills/plugins paths: 59, +5,280/−179; includes model roles as well as plugin inventory/discovery and settings integrations. Upstream ClaudeSkills already handles installed plugins; retain only missing discovery/inventory behavior.
    • The roadmap's basic LaTeX rendering request is already covered upstream: ChatMarkdown uses remark-math. The fork's current Markdown diff largely concerns issues and inline terminals, so deleting that whole diff in the name of “math parity” would be wrong.

    3. What past syncs actually cost

    I inspected git log --merges, merge parents, incoming commit counts, and changed-path intersections. Conflict counts below are the recorded merge-tree measurements in #374 and #368, corroborated for the latest two by their closeouts. I did not run a writing trial merge.

    Sync Actual merge Incoming commits from parent history Paths touched by both sides Recorded conflicted files / blocks
    Oct 31 3db991c2d6 401 209 61 / 99
    Nov 1 c8ef40483a 175 108 22 / 27
    Nov 2 211ae538be 176 163 31 / 54
    Nov 11 436c0d0f32 1,064 376 125 / 281
    Nov 12 5acdb8245f 451 231 47 / 87

    Across five syncs: 286 file-conflict occurrences and 548 blocks (repeat files counted again). The November 3–10 gap accumulated the biggest batch. This supports smaller regular syncs, but does not prove elapsed labor savings: history does not contain reliable agent-hours or token costs.

    The Nov 12 closeout reports 65 lost-code audit entries: 22 restyled, 33 replaced upstream, 10 restored; extensive validation still left Knip and an out-of-scope provider assertion unresolved at that report. Nov 11 reports 99 audit flags, with 24 upstream replacements and 11 restored flags. Rerere recorded resolutions but replayed none in that sync. A clean textual merge is insufficient evidence of preserved behavior.

    Management verdict: the single main branch and periodic real upstream merges are appropriate for this continuously evolving integrated application. Keep upstream ancestry: sync commits must retain the upstream parent rather than squash away that relationship. Task PRs may be linearized separately. The fork guide's blanket rebase wording should be clarified for syncs, because the actual history correctly contains two-parent upstream merges.

    Alternative Assessment
    Rebase all custom history onto each nightly Reject as default: replays a large patch history, rewrites shared commits, and still requires semantic reconciliation. Reasonable only after a deliberate reduced patch-stack redesign.
    One main + real upstream merges Keep. Preserves ancestry and already works; reduce the customized shared surface.
    Separate feature packages/modules Recommended selectively. Start with existing owned modules and a few typed hooks. A package boundary alone does not solve shared event/state ownership.
    Replace with upstream equivalents Highest-value deletion when behavior is truly equivalent; use per-behavior evidence, especially for project filtering, ownership and recovery.
    Contribute upstream Offer small generally useful fixes or seams after owner approval. Do not make acceptance of a large personal orchestration product a dependency.
    External plugin/service for everything Not recommended now: native UI and transactional ownership lack an established extension boundary; would add RPC/state duplication.

    4. Ranked plan

    Cost bands are design estimates, not measured duration: S one focused area; M several connected files with focused behavior proof; L cross-layer state/lifecycle integration with migration or recovery proof. No implementation is authorized by this report.

    1. Adopt this nightly with an explicit behavior replacement ledger (L). Preserve real upstream ancestry, fork migration ledger and lost-code audit. For each contested behavior record keep / replace with cited upstream symbol / retire with owner decision. Focus proof on project organization, issue admission/ownership, delegated cancellation/completion/questions, Writer routing, Codex/Claude recovery, artifacts/PDF and notebooks. Check migrations on a disposable copy before delivery. Do not combine this with a wholesale architecture rewrite.
    2. Make upstream delegation the sole execution mechanism (L, highest sustained payoff). Keep issue eligibility, root ownership, role selection, handoff and attempt policy in issue-owned services/command modules. Translate decisions into existing upstream launch/cancel/complete primitives. Reduce edits in Orchestrator, EffectWorker, ProjectionStore, Codex/Claude adapters and OrchestratorMcpService. Preserve atomic receipt/event/outbox guarantees: moving work to a post-hoc observer that can lose claims is not an acceptable shortcut.
    3. Rebuild project-view composition around upstream project/row primitives (M–L). Keep custom section layout in one owned component and one layout-state owner; reuse upstream grouping, pin/archive, folder expansion and common row actions where compatible. Preserve global activity filtering separately from expansion. Removing custom sections is an optional product decision, not an implementation assumption.
    4. Consolidate usage and role policy (M). Consume upstream usage facts and target/options contracts; keep configured role order, headroom sorting and Writer policy in small owned modules. Evaluate reset-credit automation separately from usage display. This reduces provider/MCP duplication without removing the owner's model choices.
    5. Finish the smaller seams and retire proven duplicates (S–M each). Keep PDF annotations over the upstream viewer; notebook execution over saved-notebook preview; project artifacts as an owned service/toolkit. Consolidate plugin discovery with upstream readers. Audit storage cleanup, shell/process controls and desktop update behavior individually. Offer small reusable fixes upstream only with approval; basic math rendering needs no independent fork engine.
    6. Reduce optional product scope only after owner choices (M). Candidates: unused Forgejo/GitLab/git-bug adapters, reset-credit automation, notebook execution or custom section hierarchy. Removing an adapter's new writes does not authorize deleting historical records or migrations. Preserve readable existing data.

    Success should be measured by fewer changed lines in the named upstream hot files, fewer repeated conflict paths, and fewer restoration findings in the next sync audit—not simply by moving files or reducing total test lines.

    5. Decisions for the owner

    Decision Options Recommendation
    Project organization Keep full custom hierarchy; accept flat upstream folders/pins; retain current implementation indefinitely Keep the hierarchy, convert shared primitives. Flat upstream is cheaper only if losing section/subsection dragging and custom controls is acceptable.
    Issue workflow Keep managed queue/root ownership; reduce to links and manual delegation; move outside T3 Keep managed policy inside T3, use upstream execution. It is the major distinct capability.
    Sync strategy Regular real merges; full rebase/patch stack; stop tracking nightlies Real merges on one main with bounded batches and explicit replacement evidence. Clarify sync exceptions to linear task history.
    Supported issue hosts GitHub only; all four hosts; selected subset GitHub-only active support if the other hosts are no longer used. Retain historical readability; usage is unverified, so this is a decision, not permission to delete.
    Roles/usage/Writer Keep policy; use only upstream generic roles and raw quotas; partial simplification Keep configured roles and Writer owner-routing; share usage readers and execution. Decide separately whether automatic reset-credit consumption remains desired.
    Upstream contributions Approve small general fixes/seams; maintain privately; propose the entire feature suite Small contributions when reusable and approved. Do not block local convergence on upstream accepting personal workflow policy.

    No files, branches, worktrees, refs or live userdata were modified. No builds, tests, browser sessions or runtime migrations were run. This establishes source/history overlap and a plan, not mergeability or behavioral parity of a future implementation. Mobile and other providers are outside the recommendation scope.

  2. tannerpolley commented on Nov 16, 2026

    @tannerpolley
    OwnerAuthor

    Owner decisions (2026-11-16)

    The owner took the recommendation on each of the four questions asked:

    • Project view: keep the section hierarchy, dragging and controls, and rebuild them on upstream's project rows, grouping and pin/archive (plan step 3).
    • Issues and orchestration: keep the managed queue, repository orchestrator, roles and handoffs, but run all launching, cancelling and completion through upstream's delegation code (plan step 2).
    • Issue hosts: GitHub only. Remove write support from the Forgejo, GitLab and git-bug adapters, and keep old records readable (part of plan step 6).
    • Upstream contributions: small, reusable fixes and hooks only, each posted only after the owner approves it.

    Not asked, recommendations stand:

    • Sync strategy: real merges on one main.
    • Roles, usage and Writer: keep the policy and share the usage readers (step 4).
    • Reset-credit automation: to be decided separately.

    The plan steps are split into sub-issues of this issue.

  3. tannerpolley commented on Nov 20, 2026

    @tannerpolley
    OwnerAuthor

    Closing as done (owner, 2026-11-20 issue audit). The comparison, ranked plan and owner decisions are posted, and the chosen nightly sync landed in 7abb7f1. The remaining scope is in #420; #421 is closed separately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions