linscp — Qt port of WinSCP

Plan, tasks, tracker and estimates

linscp — Qt port of WinSCP

A cross-platform (Linux + Windows) Qt frontend over WinSCP’s protocol core, built so that upstream WinSCP remains trackable with near-zero merge cost.

Documents

File Purpose
PLAN.md Architecture, strategy, repo/branch model, risks
TASKS.md Work breakdown with stable task IDs
TRACKER.md Live status per task
ESTIMATES.md Effort model, including AI-assisted estimate

Goal

One codebase. Qt UI. Builds and runs on Linux and Windows. No Embarcadero C++Builder in the toolchain.

Current state (2026-10-10)

Phase 0 is 23 of 34 done; Phase 1 is 9 of 30. Upstream is pinned to the latest stable release, 6.5.8.

source/core/Option.cpp compiles cleanly against the shim on Linux and Windows — the first real WinSCP core translation unit to build, on both platforms. Across the nine tracked units, with nothing aborting on either target, the counts are 1,334 errors on Windows and 1,575 on Linux, ratcheted in CI per target so neither platform can drift ahead unnoticed.

The shim covers UnicodeString, the byte-string family with a UTF-8 codec, TDateTime, the Delphi exception hierarchy, TCriticalSection, TStrings/TStringList, directory search, TClosure for __closure, the free string/number/path routines, TVarRec/Format, and a Win32 subset for POSIX. 15 test binaries pass on Linux and on Windows under Wine.

The three findings the plan rests on

  1. __property is emulatable. clang supports __declspec(property) under -fms-extensions, verified on this machine (Debian clang 19) for every form WinSCP uses: field-backed r/o, field-backed r/w, method-backed with validating setter, read-modify-write, and indexed. GCC does not — clang is mandatory. WinSCP’s own compiler is already clang-based, so this is not a compiler-family change.

  2. Windows binaries can be produced on Linux. clang emits valid x86-64 COFF for x86_64-w64-mingw32, lld static-links it, and the result runs under Wine — the full test suite does exactly that on every build.

  3. The de-VCL’d core already exists and is maintained. Far-NetBox (last commit 2026-07-24, tracking WinSCP 6.5.6 — one minor behind our pin) builds WinSCP core with MSVC/CMake over a hand-written ~16.3k-line VCL replacement in src/base/. It is Win32-targeted and its frontend is useless to us, but it is a proven reference for the hardest subsystem.

Non-negotiable constraints

Plan

1. Answers to the four framing questions

Q1 — Can we compile the Windows version here on Linux and test it?

Two different questions, with two different answers.

Today’s VCL WinSCP: no. It requires Embarcadero C++Builder 11 (bcc64) plus MSBuild, the VCL runtime, and .dfm form compilation. The toolchain is Windows-only, proprietary, and has no cross-compiler. There is no path to building the current WinSCP.groupproj on Linux, and this will never change.

The Qt branch: yes. Verified on this machine:

clang++ --target=x86_64-w64-windows-gnu  -fms-extensions  -> x86-64 COFF  OK
clang++ --target=x86_64-pc-windows-msvc  -fms-extensions  -> x86-64 COFF  OK
clang++ --target=x86_64-pc-linux-gnu     -fms-extensions  -> ELF 64-bit   OK

All three with __declspec(property) emulation working. So one compiler (clang) covers all targets, which matters because GCC cannot compile the property shim at all.

Toolchain decision: clang + mingw-w64 (*-windows-gnu), not clang-cl. Rationale: no MSVC licence or xwin SDK download needed, a single libc++/libstdc++ story, and Debian ships the full mingw-w64 sysroot in apt. Keep the windows-msvc target as a later option if MSVC ABI interop is ever required.

Two real gaps, both solvable:

Testing: Wine 10.0 is in apt. Good enough for CLI smoke tests and most Qt GUI behaviour. It is not sufficient to certify a Windows release — a real Windows CI runner is required before shipping binaries.

Q2 — A Qt branch that generates Windows builds and tracks upstream cheaply

See §3 Upstream tracking model. Short version: the port never contains a modified copy of WinSCP source. A committed script transforms the pinned submodule into a generated tree at build time.

Q3 — One codebase, Qt, both platforms

Endorsed as the end state, with one consequence worth stating plainly: Windows users lose the native-feeling VCL UI in exchange for a Qt one. That is the real cost of this project and the reason upstream would never undertake it. It also means C++Builder — a paid, proprietary, Windows-only compiler, and today the single largest barrier to outside contributors — leaves the toolchain entirely.

Q4 — “Shims get removed once the maintainer adopts it, and by then the UI must be 100% ported”

This is the one place the plan diverges from the brief. Three corrections.

(a) Most shims are not scaffolding — they are the permanent portability layer. The UnicodeString / TStrings / TDateTime shim is not a temporary adapter; it is the cross-platform RTL. Deleting it means replacing 5,178 UnicodeString and 497 TStrings uses across the core with std::wstring/QString and STL containers — a second project comparable in size to the first, with no user-visible benefit and a large regression risk. Recommendation: keep it permanently. A stable, well-tested 16k-line shim nobody has to look at is a feature, not debt.

What should eventually be deleted is different and much cheaper: the VCL frontend, the Windows-only Pascal packages, and the dual-target #ifdef __BORLANDC__ branches. That is Phase 4, and it is weeks of work.

(b) Do not couple cleanup to 100% UI parity. These are independent axes, and coupling them creates a trap: you would carry the dual-build burden for an extra year waiting on the last few preference dialogs. The correct trigger for retiring the VCL build is parity on the features users actually depend on, which lands well short of all 48 dialogs. Decoupling them also means a stall in UI work never blocks toolchain cleanup.

(c) Do not make an architectural decision contingent on a social outcome. The maintainer has publicly called a Qt rewrite an “inconceivable task”. Plan for this fork to stand alone and be sustainable indefinitely; treat upstream adoption as upside. The “keep the VCL build green” discipline in §3 is what maximises the chance of adoption — but the architecture must not depend on it.


2. Architecture

┌─────────────────────────────────────────────────────────────┐
│  qt/            Qt 6 frontend            (ours, new)        │
│  vcl-frontend/  existing VCL UI          (upstream, frozen) │
├─────────────────────────────────────────────────────────────┤
│  core/Interface.h — the frontend contract (upstream, as-is)  │
├─────────────────────────────────────────────────────────────┤
│  WinSCP core: SFTP SCP FTP WebDAV S3     (upstream, as-is)  │
│  PuTTY 0.85 · FileZilla FTP engine       (upstream, patched)│
├─────────────────────────────────────────────────────────────┤
│  port/shim/      VCL RTL replacement     (ours, permanent)  │
│  port/platform/  POSIX + Win32 helpers   (ours, permanent)  │
├─────────────────────────────────────────────────────────────┤
│  OpenSSL · expat · neon · libs3          (system packages)  │
└─────────────────────────────────────────────────────────────┘

core/Interface.h already is a clean abstract frontend contract — free functions and virtuals (ShowExtendedException, CopyToClipboard, ProcessGUI, CreateConfiguration, StartThread). The core never calls the GUI directly. ProcessGUI is virtual on TSessionUI, so a headless frontend no-ops it. Config storage is already abstracted behind THierarchicalStorage with both registry and INI backends; Linux uses the INI path. We are filling in an existing seam, not cutting a new one.

The dual-target macro — the keystone of the whole plan

The __property rewrite expands to native VCL syntax on C++Builder and to __declspec(property) everywhere else:

#ifdef __BORLANDC__
  #define PROP_RW_GS(T, Name, G, S) __property T Name = { read = G, write = S }
#else
  #define PROP_RW_GS(T, Name, G, S) __declspec(property(get=G, put=S)) T Name
#endif

This makes the transformation non-destructive: the same transformed header compiles under C++Builder and under clang. That single property is what lets the VCL build stay green, what makes the diff theoretically acceptable upstream, and what keeps the port honest.

Property forms in core, all mechanically rewritable:

Form Count
read = FField 576
write = SetX 362
read = GetX 246
write = FField 182
index = … (4 hand-written wrappers) 4
default / nodefault / stored 0

591 declarations across core headers; four exceptions. Everything else is a one-line-in, one-line-out substitution.

Other Embarcadero extensions: __fastcall (5,277 sites) becomes an empty #define — zero diff. __closure (45 sites) becomes a macro over a std::function-alike. ARRAYOFCONST (29) needs a variadic shim. Delphi Set<> appears once in core.

Win32 call sites in core

Roughly 200 direct Win32 calls across ~40 distinct functions (CreateFile, ReadFile, GetFileAttributes, FindFirstFile, WSAEventSelect, CreateEvent, one RegQueryValueEx, one SHGetFolderPath). Rather than edit core, implement that subset in port/platform/win32-on-posix/. This keeps the core diff at zero at the cost of a contained, well-understood compatibility module. WSAEventSelect semantics are the awkward part; everything else is routine.

Stored-password crypto is not DPAPI — core uses its own Cryptography.cpp, so it ports cleanly.


3. Upstream tracking model

Generated-tree model. This repo contains zero modified WinSCP source.

linscp/
├── 3rd-party/winscp/      submodule, pristine upstream, pinned to a tag
├── port/
│   ├── tools/transform.py committed, re-runnable, line-preserving
│   ├── patches/*.patch    small series for what cannot be mechanised
│   ├── shim/              VCL RTL replacement        (first-class source)
│   └── platform/          POSIX + Win32-on-POSIX     (first-class source)
├── qt/                    Qt 6 frontend              (first-class source)
├── cmake/
└── build/gen/             generated transformed tree (gitignored)

Build = transform.py reads the submodule → writes build/gen/ → compile build/gen/ + port/ + qt/.

Updating to a new WinSCP release:

  1. git -C 3rd-party/winscp fetch && checkout <new tag>
  2. Re-run transform.py
  3. Re-apply the patch series; fix rejects
  4. CI runs the golden-output suite on Linux + Windows

Your diff against upstream is structurally empty, so there is nothing to conflict. The maintenance burden is the script and the patch series, not 77k lines of forked code. Anything the script cannot express mechanically is a deliberate decision recorded as a patch — which keeps the patch series small by construction, because a growing series is an immediate, visible warning sign.

This is exactly what the submodule you asked for is good for: a pristine upstream reference, not a vendored copy to edit.

Branches

Branch Role
main the port: port/, qt/, doc/, submodule pin
upstream-pin/* tags recording which WinSCP commit each release was built against

No long-lived divergent branch is needed, because there is no forked source to diverge. This is the structural reason to prefer this model over forking winscp/winscp outright.


4. Incremental UI strategy

Do not mix VCL and Qt in one process. It is technically possible on Windows and a maintenance disaster, and it is impossible on Linux where VCL does not exist. “Incremental” must mean something else.

The workable model: two independent frontends over one ported core.

The Qt app becomes the default when it is good enough; the VCL build is retired in Phase 4. Users are never handed a half-ported UI, and UI work can stop and restart at any point without breaking anything.

The .dfm designer files are an asset here, not an obstacle: each is a declarative spec of a dialog’s layout, widgets, captions and tab order, which makes .dfm → .ui conversion unusually tractable and reviewable.

The 121k lines of Pascal component packages are deleted, not ported — all seven map onto functionality Qt already ships:

Deleted Replaced by
Toolbar2000 + TBX (32k) QToolBar / QMenuBar
filemng shell tree (14k) QFileSystemModel
JCL (59k) utility code; drop
PngComponents (4.6k) Qt native image support
dragndrop (3.6k) Qt native drag & drop

Translations in translations/ should be reused rather than rewritten; mapping WinSCP’s string tables onto Qt’s tr()/.ts pipeline is a task in its own right (P3-07) and is worth doing early enough to avoid hardcoded strings accumulating.


5. Verification strategy

The thing that makes this port tractable to verify, not just write:

Golden-output differential testing. WinSCP’s scripting frontend emits deterministic XML session logs — the same protocol the netstandard2.0 .NET assembly already consumes. So:

  1. Build a corpus of scripts covering SFTP/SCP/FTP/FTPS/WebDAV/S3 operations.
  2. Run each against real WinSCP on Windows → golden XML.
  3. Run each against the port → candidate XML.
  4. Normalise (timestamps, paths, session IDs) and diff.

This gives a regression suite over the core port for a fraction of the cost of writing unit tests for 77k lines, and it is the single highest-leverage item in Phase 0. Protocol servers come from containers (OpenSSH, vsftpd, ProFTPD, Apache/WebDAV, MinIO) so the matrix runs in CI.

Corollary benefit: the existing .NET assembly targets netstandard2.0 already, so it will drive the Linux port unchanged once the CLI speaks the same protocol.


6. Risks

# Risk Severity Mitigation
R1 C++Builder rejects __property produced by macro expansion, killing the dual-target keystone High Cheap to test — one header, one person with a licence, Phase 0. Macros expand before parsing and bcc64 is clang-based, so confidence is high but it is unverified here. If it fails, the VCL build cannot stay green and §3’s upstream story weakens considerably. Test this first.
R2 FileZilla WSAAsyncSelect → epoll rewrite introduces subtle async bugs High ~1,700 lines of hidden-window message-pump state machine. Golden-output suite + a real FTP server zoo. Budget generously; this is the least mechanical task in Phase 1.
R3 No C++Builder licence and no Windows machine available locally Medium Windows CI runner; R1 needs a collaborator or a trial licence
R4 Qt6-for-mingw not packaged; must be built once Medium Scripted, cached CI artifact; blocks only Phase 2+
R5 Qt UI parity is the dominant cost and may stall Medium Decouple from Phase 4 per Q4(b); ship a useful subset early
R6 WSAEventSelect emulation on POSIX proves awkward Medium Core’s socket use is mostly mediated by PuTTY/FileZilla; scope is small
R7 Upstream churn outpaces the transform script Low Script is declarative and line-preserving; patch-series growth is the early-warning signal
R8 Protocol regressions reach users Medium Golden suite is a merge gate, not an afterthought

R1 is the project’s pivot point. Everything in §3 — the zero-diff upstream story, the green VCL build, the plausible path to maintainer adoption — rests on it. It is also among the cheapest things to test. Do it first, before any shim code is written.


7. Phases

Phase Outcome Gate to exit
P0 Foundation Transform script, CMake skeleton, CI on both platforms, golden harness core/Common.cpp compiles on Linux clang; VCL build still green (R1 resolved)
P1 Headless core Core + CLI on Linux and Windows, one codebase Real SFTP/FTP/S3/WebDAV sessions pass the golden suite on both platforms
P2 Qt shell Minimal usable GUI client: connect, browse, transfer, queue A user can do a day’s work in it
P3 Qt parity Commander, sync, editor, dialogs, i18n Parity on features users depend on
P4 Cleanup VCL frontend retired, dual-target #ifdefs collapsed Single-toolchain build; C++Builder gone

P0 targets Windows first, because Far-NetBox already proves the de-VCL’d core compiles for Windows. That separates “does the shim work” from “does POSIX work” instead of hitting both risks simultaneously.

Tasks

Stable IDs. Never renumber — append. Status lives in TRACKER.md.

Size: S ≤ 2 days · M ≤ 1 week · L ≤ 1 month · XL > 1 month (split before starting)


P0 — Foundation & proof

Goal: prove the keystone works, with no behaviour change anywhere.

ID Task Size Depends Notes
P0-01 Repo layout: port/, qt/, cmake/, build/gen/ gitignored S — Per PLAN §3
P0-02 Pin submodule to a release tag, not master S P0-01 Done: 6.5.8, the latest stable. The 6.6.x line is all RC/beta
P0-03 Dual-target property macro header (port/shim/vcl_property.h) S — The keystone; PLAN §2. Every form routes through a public wrapper so private accessors stay reachable, as Borland’s do
P0-04 Verify C++Builder accepts macro-expanded __property S P0-03 R1. Do this first. Needs a licence + Windows. Blocks the zero-diff story
P0-05 transform.py: __property rewriter, line-preserving M P0-03 591 decls, 4 forms + 4 manual
P0-06 transform.py: __fastcall, ARRAYOFCONST S P0-05 Done. __fastcall is an empty define; ARRAYOFCONST pastes onto a variadic call
P0-06d __closure: inline parameter form S P0-06b Done. Two sites in SessionInfo; declaration and definition must agree or nothing links
P0-06b __closure: TClosure type + typedef transform M P0-06 Done. 44 typedefs rewritten to TClosure<Sig>; contract measured from core (!= NULL 62, == NULL 31, = NULL 51)
P0-06c __closure: bind the bare-member-name call sites M P0-06b Done. 62 sites, compiler-discovered and committed to port/patches/closure_sites.json; resolving macro expansions to their definitions collapsed 118 reports to 62
P0-07 Transform idempotence + line-count assertion tests S P0-05 Guards against silent drift
P0-08 CMake skeleton: generate → compile one TU M P0-01, P0-05
P0-09 Minimal shim to compile core/Common.cpp on Linux clang M P0-08 The real measurement of shim cost
P0-10 Install + script mingw-w64 sysroot; clang --target toolchain file S P0-08 GCC is unusable — clang only
P0-11 CI matrix: Linux native + Windows cross, both clang M P0-10 From the first commit
P0-12 Wine in CI for Windows smoke tests S P0-11 Not release certification
P0-13 Golden-output harness: runner, XML normaliser, differ M — PLAN §5; highest leverage in P0
P0-14 Protocol server containers (OpenSSH, vsftpd, ProFTPD, WebDAV, MinIO) M P0-13
P0-15 Capture golden XML corpus from real WinSCP on Windows M P0-13, P0-14 Needs a Windows host
P0-16 ADR log (doc/qt/adr/) S — Record toolchain/ABI choices as made
P0-17 check_properties.py: compile-test every transformed declaration S P0-05 Validates macro arity across the real corpus without the full shim
P0-18 HTML render of the plan docs (build-html.sh) S — pandoc, self-contained, light/dark
P0-19 Publish repository with licence and root README S — Public, GPL-3.0; main released, qt active
P0-20 Generator for a PR-able branch against a winscp/winscp fork M P1-19 Defer until there is something worth proposing (Q-7)
P0-21 verify_transform.py: audit the generated tree against upstream S P0-05 Byte-exactness is the invariant the whole model rests on
P0-22 Rehearse history import into a winscp/winscp fork S P0-05 Validates Q-7 and measures the real conflict cost
P0-23 check_docs.py: keep TASKS and TRACKER consistent S — Enforces the tracker rule mechanically rather than by discipline
P0-24 Measure the VCL surface the core requires (census.py) S P0-05 Resolves core identifiers against real mingw/OpenSSL/stdlib headers
P0-25 ADR 0001: character width for UnicodeString S P0-24 Accepted: -fshort-wchar, std::u16string storage
P0-26 check_wide_abi.py: enforce ADR 0001 mechanically S P0-25 Wrong-ABI code links cleanly then misbehaves, so grep it
P0-27 compile_census.py: classify what a real core TU still needs S P0-09 Lets the compiler enumerate the shim gap instead of grep
P0-29 Shim stubs for the unqualified legacy RTL header names S P0-27 Classes.hpp etc.; their absence was aborting most TUs early
P0-30 Undo Win32 A/W name macros that collide with RTL names S P0-29 ReplaceText broke this way: header declared it, <windows.h> renamed the definition, link failed. Guarded by a link-time test
P0-31 Ratchet both targets and track early aborts S P0-28 Linux compiles core now; an aborting unit reports a floor, which once read as progress
P0-32 port/compat for headers missing from upstream itself S — Withdrawn: the one case, help.h, is compiled out by upstream’s WINSCP define, which the census was not setting
P0-28 census_ratchet.py: pin the census so progress cannot slip back S P0-27 Nothing in core compiles cleanly yet, so a reintroduced type would look like a passing build

P1 — Headless core on both platforms

Goal: one codebase, core + CLI, Linux and Windows. No GUI.

ID Task Size Depends Notes
P1-01 Shim: UnicodeString class L P0-25 6,248 uses. Class done; 1-based API from measured usage
P1-01b Shim: free string, number and path routines L P1-01 Done. Option.cpp reaches 0 errors
P1-01d Shim: TVarRec + Format + ARRAYOFCONST M P1-01b Done. Behind FORMAT (438 uses) and FMTLOAD (252)
P1-01e Resource strings M P1-01d Done with zero core changes: core’s LoadStr is implemented in terms of Win32 LoadString, so only that is supplied, over a table generated from upstream’s .rc files
P1-01c Shim: AnsiString / UTF8String / RawByteString + UTF-8 codec M P1-01 Distinct code-page types; wire-format correctness lives here
P1-02 Shim: TObject, TStrings, TStringList L P1-01 Done. 17 of the 30 Common.cpp errors
P1-02b Shim: TList, TObjectList, Delphi sets M P1-02 Done. Notify is virtual and core overrides it
P1-03 Shim: TDateTime + date/time RTL L P1-01 Done. 30 of 70 Common.cpp errors
P1-03b Shim: SysUtils / IOUtils / StrUtils file and path routines L P1-03 IncludeTrailingBackslash 39, ExtractFileName 29
P1-04 Shim: Exception hierarchy + Delphi exception semantics M P1-01 Done. Full C++Builder constructor set; descendants inherit it
P1-05 Shim: TCriticalSection + SyncObjs M P1-02 Done; recursive, as Delphi’s is
P1-05b Shim: TThread / StartThread M P1-05 Interface.h already abstracts thread creation
P1-08b Shim: Masks, TPath, TTimeSpan, TEncoding, TNotifyEvent, env/version globals M P1-01b Done. The long tail the census named after the big groups cleared
P1-08c Shim: XML DOM over vendored expat M P1-08b Done. Real parsing, not a stub: a stub would silently import no sessions
P1-07c port/platform: wide-character functions S P1-07 Done. glibc’s take a 4-byte wint_t, so they cannot be called under -fshort-wchar
P1-09b try/__finally for POSIX L P1-08b Done. All 179 blocks transformed, 0 unhandled, patch series still empty. Same expansion on both targets, so neither can rely on SEH
P1-06 Shim: TStream/THandleStream/TMemoryStream M P1-02 ~31 uses each; now the largest non-closure group
P1-06b Shim: TCustomIniFile/TMemIniFile/TRegistry M P1-06 Done. Real registry on Windows; on POSIX every key reports absent
P1-06c Shim: DynamicArray, Delphi handle-based file API S P1-06 Done. Reference-counted, as core’s by-value Read requires
P1-07 port/platform: Win32 types, time and error subset L P1-06 Done for the compiling surface: Option.cpp builds on Linux too
P1-07b port/platform: Win32 file and handle functions L P1-07 CreateFile/ReadFile/WriteFile/CloseHandle etc., as the census asks
P1-06d Frontend decision: select the INI storage backend on Linux S P1-06b TRegistryStorage cannot work there; core already supports the INI path
P1-08 WSAEventSelect / socket-event emulation M P1-07 R6
P1-09 PuTTY: re-import upstream unix/ backend M P1-03 Upstream maintains it; reconcile WinSCP’s patches
P1-10 PuTTY: reconcile WinSCP deltas against vanilla 0.85 M P1-09
P1-11 FileZilla: replace vendored MFC subset (CString/CFile/CTime) M P1-01 Only 4 files in libs/mfc
P1-12 FileZilla: WSAAsyncSelect hidden-window pump → epoll/poll L P1-11 R2. ~1,700 lines; least mechanical task in P1
P1-13 Build libs/ from the submodule, not system copies M P0-08 expat done: the mingw sysroot has no expat, and upstream vendors it for exactly this reason. OpenSSL, neon, libs3 to follow
P1-14 Drop puttyvs (MSVC wrapper, obsolete) S P1-09
P1-15 winscp.com shared-memory IPC → plain stdio M P1-06 Both platforms
P1-16 Headless frontend implementing Interface.h L P1-05, P1-15 Derive from ConsoleRunner.cpp — it has zero forms/ deps
P1-17 First link + first real SFTP session on Linux M P1-16 Expect a long tail of link/ABI issues
P1-18 Same core + CLI cross-built for Windows, Wine-smoked M P1-17, P0-12 Proves “one codebase”
P1-19 Golden suite green across all six protocols, both platforms L P1-18, P0-15 P1 exit gate
P1-20 Verify stock netstandard2.0 .NET assembly drives the Linux CLI S P1-19 Should work unchanged
P1-21 #ifdef out dragext, Setup.cpp, jump lists, file associations M P1-16 Windows-only or dropped

P2 — Qt shell: minimal usable client

ID Task Size Depends Notes
P2-01 Build Qt6 for mingw; cache as CI artifact M P0-10 R4; not in Debian repos
P2-02 Qt app skeleton, CMake integration, both platforms M P2-01, P1-19
P2-03 Qt implementation of the Interface.h contract L P2-02 Prompts, errors, progress, busy, ProcessGUI
P2-04 Session storage + site manager UI L P2-03 INI-backed
P2-05 Login / authentication dialogs (incl. host key, keyboard-interactive) M P2-03
P2-06 Remote file panel: model/view, columns, sorting L P2-03 QAbstractItemModel over TRemoteFileList
P2-07 Transfer engine wiring + queue UI L P2-06 Over TTerminalQueue
P2-08 Local file panel M P2-06 QFileSystemModel
P2-09 i18n pipeline: WinSCP string tables → Qt .ts M P2-03 Do early — avoids hardcoded strings
P2-10 Packaging: AppImage/Flatpak + Windows installer M P2-07
P2-11 P2 exit gate: a user can do a day’s work in it S P2-07, P2-10

P3 — Qt parity (incremental, independently shippable)

ID Task Size Depends Notes
P3-01 .dfm → .ui assisted converter M P2-02 .dfm is a declarative layout spec — very tractable
P3-02 Commander dual-pane: keyboard semantics, inline rename, custom columns L P2-08 The main draw for most users
P3-03 Synchronization UI + TSynchronizeChecklist view L P2-07
P3-04 Preferences dialogs (largest single cluster) XL → split P3-01 Split per page before starting
P3-05 Internal editor L P2-06 Or delegate to $EDITOR / system editor
P3-06 Remaining dialogs, batched in groups of ~8 of the 48 XL → split P3-01 Track as P3-06a…f
P3-07 Drag & drop: Qt native + XDS on Linux M P3-02
P3-08 Shell integration: “open in terminal”, file associations M P3-02 Per-platform
P3-09 Accessibility pass M P3-06
P3-10 P3 exit gate: parity on features users depend on S P3-02, P3-03, P3-04 Explicitly not 100% of 48 dialogs

P4 — Cleanup

ID Task Size Depends Notes
P4-01 Retire the VCL frontend; drop Pascal packages M P3-10 176k lines deleted
P4-02 Collapse #ifdef __BORLANDC__ dual-target branches M P4-01 Simplifies the transform script
P4-03 Fold the transform output into first-class source (optional) L P4-02 Only once upstream tracking is no longer a goal — one-way door
P4-04 Evaluate full de-shimming S P4-02 Recommendation: do not. PLAN §1 Q4(a) — write the evaluation down and close it

Tracker

Last updated: 2026-10-11

Legend: todo · wip · blocked · done · dropped

Progress

Phase Done Total Gate
P0 Foundation 25 35 core/Common.cpp compiles on Linux clang; VCL build green (R1)
P1 Headless core 21 36 Golden suite green, six protocols, both platforms
P2 Qt shell 0 11 A user can do a day’s work in it
P3 Qt parity 0 10 Parity on features users depend on
P4 Cleanup 0 4 Single toolchain; C++Builder gone
Total 46 95

Next three actions

Driven by compile_census.py rather than by grep counts — the compiler names what is actually blocking each unit, in dependency order.

The whole core library compiles for Windows – all 33 units in upstream’s ScpCore.cbproj, 0 errors – and now not only in the syntax-only census but as a real library: linscp-core, built by CMake with the cross toolchain. Linux: 558 errors, 14/33 clean, 4 aborting.

Link check (--target linscp-core-link, every core object forced into one executable): 197 undefined symbols on Windows, none of them the VCL shim’s or PuTTY’s. WinSCP’s PuTTY (176 units) and the crypto it builds a second time with MSVC (libs/puttyvs) both build with clang from the submodule. What remains:

Missing Symbols Task
neon, OpenSSL, libs3 from libs/ ~150 P1-13
FileZilla 28 P1-11
The frontend half of Interface.h (StartThread, ProcessGUI, …) 17 P1-16
  1. P1-13: neon, libs3 and OpenSSL from the submodule.
  2. P1-11: FileZilla’s 16 units (FileZilla.cbproj), with UNICODE.
  3. P1-16: the headless frontend, after which core links and can run.

Decisions taken

Date Decision Rationale
2026-10-10 clang everywhere; GCC unsupported GCC cannot compile __declspec(property); verified locally
2026-10-10 mingw-w64 (*-windows-gnu) over clang-cl/MSVC No MSVC licence or SDK download; sysroot is in Debian apt
2026-10-10 Generated-tree model, not a source fork Keeps the upstream diff structurally empty
2026-10-10 Keep the VCL RTL shim permanently De-shimming is a second project of similar size with no user benefit
2026-10-10 Decouple shim cleanup from 100% UI parity Coupling them would add ~a year of dual-build burden
2026-10-10 Two frontends over one core; never mix VCL and Qt in-process Impossible on Linux, unmaintainable on Windows
2026-10-10 Windows target first in P0 Far-NetBox already proves the core compiles for Windows; separates the two risks
2026-10-10 Line-preserving transform kept, but demoted from “constraint” to asserted property It costs nothing — all 591 core declarations are already single-line — and its real payoff is a reviewable zero-offset diff against upstream, not debugger ergonomics. Asserted by a test; abandon if it ever conflicts with something substantive
2026-10-10 index= properties handled by a PROP_R_GI macro rather than a patch Removes the last 4 manual cases, so the transform covers 613/613 with an empty patch series
2026-10-10 Far-NetBox used as reference; verbatim reuse deferred pending licence clarification Its README says GPLv3 but it ships the GPLv2 text (Q-6)
2026-10-10 Published as 99ecarvalho/linscp, public, GPL-3.0 main is the released state; active work happens on qt
2026-10-11 Compute cost recorded as measured token usage, not an estimate The branch so far cost $297 of Opus 5 inference (99% of tokens are cache reads). Confirms compute is not the constraint, and shows Opus 5.5 would halve it — see ESTIMATES.md
2026-10-11 VCL’s TThread class not shimmed Its only user, KeyGen.cpp, is in none of upstream’s .cbproj files and TKeyGenerator is referenced nowhere else — dead code upstream. Core’s own TSimpleThread uses StartThread and Win32 directly
2026-10-11 P1-05b scoped as Win32 kernel objects on POSIX, plus Delphi BeginThread/EndThread on both targets That is what core actually calls: 28 CloseHandle, 6 waits, 5 CreateEvent, 10 GetCurrentThreadId. BeginThread is written once over CreateThread, so upstream’s frontend StartThread ports unchanged
2026-10-11 POSIX kernel objects share one handle table, one lock and one condition variable; handle values are never reused Makes WaitForMultipleObjects over mixed threads and events — including atomic WaitAll — correct by construction. Core has a handful of threads, so the coarse lock costs nothing measurable. Never reusing values turns use-after-close into ERROR_INVALID_HANDLE
2026-10-11 Shim XML interfaces live in Xml::Xmlintf; only the _di_ aliases are global Embarcadero’s own layout. At global scope ours collided on Windows with the COM IXMLDocument from <msxml.h>. Core names them only through _di_ aliases and Xmlintf::
2026-10-11 Closure-site discovery compiles a separately transformed, unbound tree Compiling the ordinary tree saw the known sites already wrapped and “rediscovered” only new ones — it cut 62 sites to 2. Now idempotent: a second run is byte-identical
2026-10-11 VCL’s implicit SysUtils::LoadStr and Vcl.Menus::StripHotkey supplied by the shim, not by patching core Core receives both through <vcl.h> and never declares them. LoadStr is built on the existing LoadString table, so there is still one resource path
2026-10-11 Core is compiled with upstream’s own preprocessor configuration, read from ScpCore.cbproj by port/tools/upstream_defines.py Copying the list would drift. Applied by the census, closure discovery and CMake alike, shim included, because UNICODE decides which Win32 A/W function every macro names. Windows-only names are dropped on POSIX; _CRTIMP= is dropped everywhere, as C++Builder’s CRT linkage
2026-10-11 Census and discovery build the Debug configuration Its DebugAssert expressions are code that must compile too; Release compiles them out, which hid ten closure comparisons
2026-10-11 port/compat withdrawn; supersedes the 2026-10-10 decision creating it help.h was compensating for the missing WINSCP define, not a gap in upstream: with WINSCP set, PuTTY’s platform.h never includes it
2026-10-11 Closure binding covers Borland’s four shapes: Name, &Name, obj.Name / &obj.Name, p->Name / &p->Name Recorded as the method name’s column; the transform recovers the shape from the text and refuses longer chains or a call as the object. The verifier recomputes the rewrite with an independent regex, so a bug in either is caught by the other. The old binder had been emitting obj.CLOSURE(Name), invalid C++, in two units nothing yet compiled
2026-10-11 Win32 APIs core calls under the bare name get forwarding functions, not their A/W macros vcl_win32_undef.h removes the macros so they cannot rename the shim’s VCL functions; it had also removed CreateFile and four others core calls as the API, leaving those calls nothing to bind to. Exact signatures, so core’s NULL arguments still convert
2026-10-11 __int64 is clang’s MS-extension keyword, never a macro A long long macro – ours, and mingw’s own – breaks core’s __int64(x) functional casts
2026-10-11 Random is Delphi’s own generator It reproduces the published Turbo Pascal / Delphi sequence from a zero seed exactly, which the test pins
2026-10-11 C++Builder’s static class properties become static const pointers (TEncoding::UTF8) clang accepts static __declspec(property) but compiles it as a plain static member, failing only at link (see verified facts). Pointers serve both of core’s spellings, as a value and through ->; [[clang::require_constant_initialization]] guarantees no static-init-order exposure
2026-10-11 Win32MajorVersion() and friends are functions, read from RtlGetVersion Core calls them as functions. GetVersionEx reports 6.2 to an unmanifested executable, which would turn core’s IsWin10() false on 10 and 11. Computed on first use, which also removes a dynamic-initialiser hazard
2026-10-11 StaticArray<T, N> keeps one slack element, filled by its owner with a value no input matches Core passes Size() as an open array’s high index (ParseShortEngMonthName) and reads one past the end. In C++Builder that is whatever follows; here it is defined and means “not found”
2026-10-11 The census measures every core unit in ScpCore.cbproj, read from the project, in parallel Ten units were a sample. Reading the list from upstream means a unit it adds fails the ratchet until baselined, rather than going unmeasured. 66 compiles take about 5 s
2026-10-11 Case-mismatched upstream includes get checked-in forwarding headers in port/casefold They resolve only on case-insensitive file systems, so a Linux host fails even when cross-compiling for Windows. Explicit, not generated: a basename match would have mapped putty/windows/gss.c’s security.h – the Windows SDK header – onto core’s Security.h. check_include_case.py applies a same-directory rule and fails on drift either way
2026-10-11 ARRAYOFCONST expands to C++Builder’s two arguments, a TVarRec pointer and the high index Core’s own functions take open arrays that way (ExecCommand, ExtException), so a single container argument cannot reach them. The count comes from sizeof over an unevaluated call, so each value is evaluated once – C++Builder’s macro evaluates them twice
2026-10-11 The XML DOM follows Delphi’s model: text and comment nodes as children, Null attribute variants, raising loaders FileZilla keeps a site’s name as a text node among element children, found by NodeType; core tests absent attributes with IsNull(); and ImportFromFilezilla has no handler around LoadFromFile, so a malformed file must raise rather than import nothing. The earlier bool loaders were a divergence justified by a wrong reading of core
2026-10-11 TCustomIniFile’s virtuals take parameters by value, and its abstract set is Delphi’s eight C++Builder declares Delphi virtuals that way and core’s TOptionsIniFile overrides with exactly those signatures; by-reference parameters made its methods new functions and left the class abstract
2026-10-11 TStrings::Text uses CRLF on both platforms Delphi’s POSIX RTL uses LF. Core builds configuration and server-facing text through Text, and identical output everywhere matters more
2026-10-11 try/__finally brace depth is measured over code only A } inside a comment in a __finally body put LINSCP_END_FINALLY one brace early in ScpFileSystem.cpp. Comments and string/character literals are now blanked before counting; still 179 blocks
2026-10-11 The transform finds its patch series relative to itself, and a missing one is an error CMake runs it from the build tree, where the relative path found nothing: every CMake-built tree had no closure bindings at all, and the verifier, loading the same way, agreed. The census ran from the repo root and never saw it. bind_closures.py --require-bound now checks the tree the build compiles
2026-10-11 Header function definitions at namespace scope get inline (transform rule, verified) Common.h defines IsWideChar without it: one definition per including unit, 31 in all, which C++Builder’s linker tolerates and the standard forbids. A rule rather than a patch, so a new one upstream is handled too; a global --allow-multiple-definition would have hidden real duplicates
2026-10-11 The shim’s ExpandEnvironmentVariables removed Core defines it itself, with Windows %VAR% semantics through ExpandEnvironmentStrings. The shim’s was an invented POSIX $VAR variant, a duplicate the syntax-only census could not see. Linux gets ExpandEnvironmentStrings with Windows semantics instead (P1-07b)
2026-10-11 Include paths with backslashes are normalised to / (transform rule, verified) Only Windows resolves #include "ssh\gss.h"; clang accepts it when targeting Windows and not otherwise. Six such includes, five in core: part of why units abort on Linux. A forwarding file named with a backslash would break Windows checkouts
2026-10-11 The patch series exists, applied before the rules, strictly: exact context, line counts preserved First patch: putty-64bit-conf-defaults.patch. WinSCP stores string option defaults as (int)"..." in an int-first union, which truncates pointers on x86-64; the first union member becomes intptr_t. Upstream is built 32-bit only, so this is new territory for its code
2026-10-11 Defines are per project, not global PuTTY is built without UNICODE, core and FileZilla with it, and UNICODE decides which Win32 A/W function each macro names. Core’s are public on the shim, so everything built against it sees them
2026-10-11 Core’s overrides of PuTTY symbols are expressed by weakening PuTTY’s copies in the archive PuttyIntf.cpp redefines appname and get_remote_username, relying on C++Builder’s linker keeping the first definition. GNU objcopy marks PuTTY’s weak (llvm-objcopy cannot for COFF); check_overrides.py keeps overrides.txt exact. Sources untouched, and dual-target, which a weak attribute in a patch would not be
2026-10-11 aes-ni.c is compiled with -msse4.1 -maes, its CPU check verified free of those instructions WinSCP dropped PuTTY’s per-function target attributes, which MSVC does not need; restoring them would break the MSVC build of the same file. check_isa_free.py disassembles aes_ni_available and fails on any SSE4.1 or AES-NI instruction
2026-10-11 Case-mismatched includes are respelled in the generated tree (transform rule); port/casefold withdrawn Supersedes the forwarding headers: once FileZilla compiles from the generated tree, a forwarder to the pristine header would mix untransformed code into a transformed unit. Same same-directory rule, now a verified transform rule; core, PuTTY and FileZilla all include from the generated tree
2026-10-11 FileZilla and WinSCP’s MFC subset join the transform’s scope; two more patches mfc-x86-64.patch: the subset keys off _X86_ where it means “not 32-bit”, so it wants an unvendored afxv_cpu.h, withholds GetLength64 and asserts on I64. filezilla-ws2tcpip-case.patch: <Ws2tcpip.h>, the only system include whose case only Windows forgives
2026-10-11 MFC and FileZilla units are compiled with a forced prelude: <windows.h> without its A/W macros FileZilla includes afx.h before any core header, so MFC’s members were declared under the macros (CString::LoadString became LoadStringW) and then called without them. The prelude drops windows.h’s outer guard after removing the macros, so afx.h’s include-order check passes and its re-include brings nothing back. MFC’s CString::LoadString then reaches the shim’s resource table, which already holds FileZilla’s strings
2026-10-10 A PR-able branch against winscp/winscp will be generated, not hand-maintained linscp shares no history with upstream, so its qt branch is not directly mergeable. Since the port is mechanical, the fork branch can be produced on demand (Q-7). Rehearsed end to end — see facts below
2026-10-10 Transform must be byte-exact outside property lines A full-file rewrite (CRLF loss) turned a 613-line change into 76,551. Now asserted by verify_transform.py
2026-10-10 Field/accessor classification is convention-first, parens only as fallback The parens heuristic false-positives on constructor initialiser lists; WinSCP’s F<Upper> / Get*/Set* convention is airtight. Truly unclassifiable names now fail the run instead of producing a wrong-arity macro
2026-10-10 Windows releases link statically via lld -fuse-ld=lld -static -L/usr/x86_64-w64-mingw32/lib; leaves only KERNEL32 and msvcrt as deps
2026-10-10 CMake hard-fails on non-clang compilers A clear configure-time error beats a confusing failure in the first transformed header
2026-10-10 The transform stamp lives outside the generated tree verify_transform.py treats any extra file as a violation, which is the behaviour we want; the stamp was the first thing it caught
2026-10-10 Accepted (Q-8): -fshort-wchar with std::u16string storage; std::wstring banned in port/ Only option leaving upstream’s thousands of L"..." literals untouched. Enforced by check_wide_abi.py and a static_assert. ADR 0001
2026-10-10 -fshort-wchar set globally, not per-target One translation unit without it is an ABI landmine that links cleanly
2026-10-10 UnicodeString case folding is ASCII-only for now Delphi’s is locale-aware; core uses it on protocol tokens and switch names. Recorded as a known limitation, not silently equivalent
2026-10-10 vcl.h transitively exposes the Win32 API Matches C++Builder, which upstream’s CorePCH.h depends on: it includes <vcl.h> and core’s headers before <Winapi.Windows.hpp>. Fixing this alone removed 9 of 24 missing types
2026-10-10 UTF-8 decoding substitutes one U+FFFD per maximal subpart Unicode’s recommended practice. The first implementation emitted one per byte; a test on truncated input caught it
2026-10-10 Byte strings keep C++Builder’s code-page template shape Core relies on RawByteString and UTF8String being distinct types; collapsing them would let byte reinterpretation happen silently
2026-10-10 Date and time are combined only through ComposeDateTime Delphi keeps the time of day positive for negative dates, so Date + Time lands a day late at the mirrored time. Correct for file timestamps, wrong in general and wrong silently
2026-10-10 TCriticalSection wraps std::recursive_mutex Delphi’s is re-entrant; a plain std::mutex would deadlock on core’s re-entrant paths rather than fail a test
2026-10-10 Compile-census numbers are ratcheted in CI No core TU compiles cleanly yet, so a reintroduced missing type would otherwise present as a passing build
2026-10-10 TStrings is 0-based while UnicodeString is 1-based Both match their Delphi originals. Two bases in one codebase is a hazard, so each is pinned by a boundary test rather than left to memory
2026-10-10 TStrings references objects, never owns them Delphi does not free them and core owns them elsewhere; freeing here would be a double-free. Asserted by a test that outlives the list
2026-10-10 Chained subscripts on indexed properties are unsupported clang reads Prop[i][j] as a two-argument getter call. Core has 0 occurrences; check_properties.py fails if an upstream change adds one
2026-10-10 Win32 A/W name macros are undone in vcl_win32_undef.h <windows.h> renamed the definition of ReplaceText to ReplaceTextW while the header still declared ReplaceText. Both compiled; only the link failed, and only because a test called it. A link-time guard now references every colliding name
2026-10-10 ARRAYOFCONST pastes its parenthesised list onto a variadic call C++Builder builds an open array of TVarRec, which needs compound literals. ARRAYOFCONST((a, b)) becoming MakeFormatArgs(a, b) is ordinary C++
2026-10-11 XML is parsed for real, using the expat upstream vendors, rather than stubbed A stub would silently import no FileZilla sessions. The mingw sysroot has no expat, so the vendored source is compiled for both targets, which also keeps them on one version
2026-10-11 Wide-character functions are renamed and the CRT names redirected by macro They cannot be redeclared – <string> pulls in <cwchar>, whose wcschr differs from ours only in return type – and a macro also guarantees core’s calls reach ours rather than glibc’s
2026-10-11 towlower/towupper fold ASCII only, on both platforms The Windows CRT folds only ASCII in the default locale, confirmed by running the test against it. Folding Latin-1 on POSIX alone would make the platforms disagree, which is worse than being narrow
2026-10-11 try/__finally uses the same lambda expansion on both targets SEH would work on mingw, but one code path on both platforms is worth more than relying on it, and it removes a way for the two to diverge in behaviour
2026-10-11 The try/__finally transform measures brace depth on the pristine lines and applies every edit afterwards LINSCP_END_FINALLY replaces a } with text containing no brace, so editing in place miscounted the depth of any enclosing block – and core nests these
2026-10-11 One bare return inside a guarded body is permitted, by checked condition Returning from the lambda runs the cleanup through the guard and then falls off the end of the function, which is what Borland does – but only when the block ends the function and the return carries no value. Both are verified rather than assumed
2026-10-11 Every property form routes through a generated public wrapper Borland’s __property grants access to a private accessor from outside the class and ignores constness; __declspec(property) does neither, because it expands to an ordinary member call at the use site. The wrappers restore both behaviours, and the getter casts its result to the declared type because C++Builder is lax where the two differ in constness
2026-10-11 UnicodeString accepts numbers implicitly, yielding their decimal text C++Builder does, and core depends on it. The hazard is real – UnicodeString s = 0; gives "0" – but diverging would mean editing core
2026-10-11 Globals that need dynamic initialisation are declared before the object that initialises them Within a translation unit, dynamic initialisation runs in declaration order. Putting the initialiser first had its constructor assign to a UnicodeString that was not yet constructed, which segfaulted rather than failing to compile
2026-10-11 TMask matching is case-insensitive Delphi’s is, and core uses it for file masks users type without regard to case
2026-10-11 Closure call sites are compiler-discovered, committed, then replayed The sites cannot be inferred by regex: whether an argument is a closure depends on the callee’s signature. clang names each one exactly, so discovery records them to port/patches/closure_sites.json and transform.py replays that list, failing loudly if a recorded site no longer holds the expected identifier
2026-10-11 A diagnostic inside a macro expansion is resolved to the macro definition clang reports it at the expansion point, so SessionInfo.cpp’s ADSTR macro alone produced 61 duplicate reports. Binding the definition once fixes every call site, and cut the work from 118 sites to 62
2026-10-11 TRegistry on POSIX reports every key absent rather than empty There is no registry, and returning defaults for settings a user had actually set would look to them like their configuration had vanished. The INI backend, which core already supports, is the correct one there (P1-06d)
2026-10-11 INI section and key names match case-insensitively Delphi’s do, and files written by WinSCP on Windows have inconsistent casing
2026-10-11 INI sections and keys keep their file order Sorting them would churn the user’s configuration on every save and make diffs useless
2026-10-11 DynamicArray shares its buffer on copy, as Delphi’s does Core declares TSafeHandleStream::Read as taking one by value and fills it for the caller. A deep-copying version would compile and silently return no data
2026-10-11 win32_on_posix.h exposes <string.h>, <stdlib.h> and <stdio.h> <windows.h> does transitively, and core calls strlen, strcmp and memmove unqualified
2026-10-10 Resource strings: supply Win32 LoadString, not a .res loader, and do not patch core core’s LoadStr is already implemented, in terms of HInstance, LibModuleList and Win32 LoadString. Supplying those three means no .res binary format to parse, no core edits, and a purely additive change — the kind upstream could take rather than a fork of its own code. The table is generated from upstream’s .rc files, so the strings track the submodule automatically
2026-10-10 UnicodeString::c_str() has a non-const overload returning a writable buffer C++Builder’s does, and core depends on it: DoLoadStrFrom calls SetLength and then passes c_str() to LoadString as the destination to fill
2026-10-10 TList::Notify is virtual and fires before a removal, after an addition Core overrides it. TObjectList frees owned objects from inside it, so a wrong Action means a leak or a double free, neither of which announces itself
2026-10-10 Extract reports lnExtracted, never lnDeleted That is how Delphi lets a caller take ownership back without the list freeing the object
2026-10-10 TList::Sort is stable, where Delphi’s quicksort is not Relying on an unstable order would be a latent caller bug either way, and stable is the safer guarantee to provide
2026-10-10 Derived streams re-expose the base’s legacy Seek with a using-declaration Overriding one overload hides the other. Core calls both on derived streams, so without this the legacy origins would stop resolving
2026-10-10 Stream exceptions follow Delphi’s shape exactly EFilerError, EFOpenError and EFCreateError are siblings under EStreamError, with EReadError/EWriteError beneath EFilerError. Core catches at both levels
2026-10-10 port/platform headers refuse to compile on Windows, and are POSIX-only on the include path Putting them on a Windows target shadowed the genuine mingw headers, which presented as a 1,220 -> 783 “improvement”. The #error makes that mistake loud
2026-10-10 port/compat is separate from port/platform help.h is missing from upstream itself rather than being a platform difference, so it is needed on every target
2026-10-10 The ratchet records whether a unit aborted An aborted parse reports a floor. Treating that as a distinct state stops a new abort from reading as sudden progress
2026-10-10 Format keeps malformed input visible Delphi raises on a missing argument. Core routes user- and server-supplied text through these into logs, so an unknown specifier is echoed and a missing argument renders as <missing> rather than throwing from a log path

Correction: census figures before 2026-10-11 used the wrong configuration

Until upstream_defines.py, every compile of core here used none of the defines upstream builds it with – not WINSCP, not UNICODE, not _DEBUG. So the census measured a configuration upstream never builds. Two effects:

It also surfaced a shim bug that only _DEBUG reaches: the POSIX TEXT() was one-level, so TEXT(__FILE__) pasted the token into L__FILE__.

The corrected census is 159 / 303. Earlier figures are not comparable with it; the trend they showed was real, the absolute numbers were not.

Correction: the earlier “5 errors left” figure was wrong

Recorded because the mistake is instructive, not just to log it.

compile_census.py filtered clang diagnostics on ': error:', which does not match ': fatal error:'. A missing header emits only a fatal error and aborts the parse, so a translation unit that never got past its first include was reported as having zero problems. The progression logged earlier for Common.cpp (109 -> 83 -> 70 -> 30 -> 13 -> 5) was real for the portion that parsed, but it was a floor, not a total: the parse was stopping at #include <Classes.hpp>.

Two fixes. The census now counts fatal errors and prints ABORTED EARLY with the cause, so an aborted unit can never again look like a clean one. And port/shim now stubs the unqualified legacy RTL header names (Classes.hpp, SysUtils.hpp, Contnrs.hpp, …) alongside the System.* spellings, since core uses both.

The honest figure for Common.cpp is 417 errors across 29 missing types, and the ratchet now covers nine translation units rather than one, precisely so a single unit cannot give a falsely rosy picture again.

Known divergences from Delphi

Recorded deliberately, so they are findable when something behaves oddly.

Area Divergence Why
UnicodeString::LowerCase / CompareIC, AnsiLowerCase / AnsiUpperCase ASCII-only case folding Delphi’s is locale-aware. Core uses these on protocol tokens and switch names. Must not be relied on for user-facing text
FindFirst pattern matching Case-sensitive on Linux, case-insensitive on Windows Each matches its host filesystem. A pattern that matches on Windows may not on Linux
faHidden on Linux Set from a leading dot in the name POSIX has no hidden attribute; the dot convention is what users expect
TFormatSettings defaults ISO-8601 rather than system locale Deterministic across machines. Anything user-facing should set them explicitly
Null arguments to the Win32 time functions Rejected on POSIX; real Win32 dereferences and faults The hardening is deliberate, so the null-argument assertions run only on POSIX
Winsock error codes on POSIX Keep their Winsock numeric values rather than mapping to errno Core and the FileZilla layer compare them by name and store them in their own state
TRegistry on Linux Every key reports absent; nothing can be read or written No registry exists. The INI backend is the correct one there, and failing visibly beats returning defaults for settings the user had set
INI share modes Windows share modes are ignored on POSIX rather than approximated Advisory locking would change behaviour rather than match it
SetThreadPriority on POSIX Recorded and reported back by GetThreadPriority, but no scheduling effect Core only lowers background queue threads; running them at normal priority is harmless
ExitThread / EndThread on POSIX Unwinds to the entry point by exception, so destructors run; Win32 skips them A catch (...) between the call and the entry point would intercept it. Core calls it only as the last statement of a thread entry point
Named events on POSIX CreateEvent with a name fails with ERROR_NOT_SUPPORTED Would need to be cross-process. Core never names one; refusing beats quietly creating a private event
StripHotkey in East Asian locales The whole-(&X) suffix removal Delphi does under SysLocale.FarEast is not reproduced Only the & is removed. Affects only CJK system locales
ParamStr(n) splitting on Windows Follows Delphi’s GetParamStr rules as documented in the shim – quotes toggle and are dropped, no backslash escapes, empty "" skipped – but has not been compared against a Delphi binary Wine cannot check it: CommandLineToArgvW implements the MSVC rules, which differ deliberately. Core itself only uses ParamStr(0)
TPath::IsDriveRooted on POSIX Always false As in Delphi’s POSIX RTL. Core uses it only to locate Windows’ UAC VirtualStore
Calling a closure through a type it was cast to Stops the program with a message Borland reinterprets the (code, data) pair, so the call is undefined behaviour there. Core only casts to launder a closure and back, which round-trips exactly
TFile::ReadAllText without a BOM Decodes UTF-8 on both platforms Delphi uses TEncoding.Default, ANSI on Windows. Core reads only authorized_keys this way and writes it back as UTF-8, so ANSI would double-encode non-ASCII comments. ASCII files are identical either way
FileSetAttr on POSIX Only faReadOnly acts, on the write permission bits; archive, hidden and system are ignored They have no POSIX counterpart. Read-only mirrors how FileGetAttr reports it
FindData.ftCreationTime on POSIX The modification time POSIX has no creation time
Variant Only one-dimensional integer variant arrays Core’s only use. Anything wider raises EVariantError so a new use is noticed
ParseShortEngMonthName("January") Returns 0, “not found” Upstream reads past ShortMonthNames into LongMonthNames[0] and returns 13, an invalid month. Every other input agrees
TFormatSettings::Create(locale) Every locale yields the shim’s deterministic defaults, with English month and day names Core asks by LCID 1033 for protocol parsing, which this matches; user-facing formatting should set fields explicitly
TEncoding::Default UTF-8 on both platforms Delphi’s is ANSI on Windows
FileGetSymLinkTarget Resolves the whole chain to an absolute path Delphi returns the immediate target. Core only reads the target’s attributes
ExtractShortPathName on POSIX The name unchanged No 8.3 names exist
ExceptAddr / ExceptionErrorMessage No addresses are recorded: ExceptAddr is null and the module is the executable The class name and message, the useful part, are exact
FormatFloat Digits, grouping, decimals, literals and sections only; scientific notation raises EConvertError Core’s one use is "#,##0"
Element Text with mixed content Concatenates the element’s text children Delphi raises when an element holds more than a single text node. Leaf elements, which is what core reads, agree
RawByteString to another code page Bytes pass through C++Builder’s RawByteString carries a run-time code page and would transcode out of it; this one has none
ISO8601ToDate without a zone designator Taken as UTC Delphi’s handling of a zoneless time is not established here; every value core parses (S3) carries Z
TStrings::Text on POSIX CRLF, not LF See the decisions table
SuspendThread on POSIX Not declared A running pthread cannot be suspended. A missing declaration fails at compile time; a stub would fail silently. CREATE_SUSPENDED + ResumeThread is supported

Open questions

# Question Blocks Owner
Q-1 P3 scope: faithful parity, or a deliberately narrower client? P3 estimate (swings ~2 years) —
Q-2 Access to a C++Builder 11 licence + Windows host? P0-04, P0-15, R1, R3 —
Q-3 Internal editor, or delegate to the system editor? P3-05 —
Q-4 Ship 32-bit Windows, or x86-64 and arm64 only? P0-10, packaging —
Q-5 Approach the maintainer early for feedback, or after P1 lands? social strategy, not architecture —
Q-6 Far-NetBox licence: README says GPLv3, LICENSE.txt is the GPLv2 text verbatim reuse of its shim (reference use is unaffected) —
Q-7 Build the fork-branch generator now, or when there is something worth proposing upstream? nothing today; recommend deferring until P1 lands —
Q-8 Confirm ADR 0001 — resolved 2026-10-10: accepted — —

Verified facts (re-check if the environment changes)

Fact Evidence Date
Upstream WinSCP is built for 32-bit Windows only PuTTYVS.vcxproj has only Win32 configurations, and PuTTY’s option defaults cast string addresses to int, which only fits in 32 bits 2026-10-11
clang accepts static __declspec(property(...)) syntactically but treats it as an ordinary static data member -fsyntax-only passes; linking fails with an undefined reference to the “property” on both targets 2026-10-11
clang 19 supports __declspec(property) on Linux under -fms-extensions Local test: field r/o, field r/w, method+validating setter, read-modify-write, indexed — all pass 2026-10-10
GCC 14 rejects it outright error: 'property' has not been declared 2026-10-10
clang cross-emits x86-64 COFF for windows-gnu and windows-msvc Local test, property emulation intact 2026-10-10
Qt6 present on this host; Qt6-for-mingw absent from Debian apt-cache search returns nothing for mingw+qt 2026-10-10
Wine 10.0 installable from apt apt-cache policy wine 2026-10-10
Core has 591 __property decls; 0 use default/nodefault/stored grep over source/core/*.h 2026-10-10
Core has no __try/__except grep 2026-10-10
ConsoleRunner.cpp has zero forms/ dependencies include analysis 2026-10-10
Stored-password crypto is not DPAPI no DPAPI symbols in core 2026-10-10
WinSCP’s own compiler is already clang-based #ifdef __clang__ in source/core/Global.h:37 2026-10-10
Far-NetBox tracks WinSCP 6.5.6, last commit 2026-07-24, ~16.3k-line VCL shim repo inspection 2026-10-10
Core has 613 __property declarations across 69 files (.h and .cpp) transform.py --check 2026-10-10
0 of 613 span multiple lines; 0 have comma-bearing or template types AST-free scan of core/*.h 2026-10-10
All 613 transform to 9 macro forms with 0 unhandled transform.py 2026-10-10
All 613 transformed declarations compile under clang check_properties.py, exit 0 2026-10-10
Transform is idempotent and line-count-preserving across all 69 files transform.py, second pass is a no-op 2026-10-10
All 8 property shapes behave correctly at runtime (incl. validating setters, read-modify-write, indexed) vcl_property.h self-test, assertions pass 2026-10-10
Cross-built Windows PE32+ binary passes the full property suite under Wine clang --target=x86_64-w64-mingw32, exit 0 2026-10-10
Static Windows link needs lld plus explicit -L for libwinpthread GNU ld fails; lld leaves only KERNEL32 + msvcrt 2026-10-10
Dynamic Wine runs need two DLL dirs on WINEPATH libwinpthread-1.dll lives apart from libstdc++/libgcc 2026-10-10
Importing linscp history into a winscp fork merges with zero conflicts git merge --allow-unrelated-histories; 10,602 commits, both roots, all port commits preserved 2026-10-10
Applied in-tree, the core transform is a 613-line diff across 23 files measured on the rehearsal fork 2026-10-10
After conversion, an upstream release touching a property line conflicts in 1 file, resolvable mechanically simulated release; checkout --theirs + re-run transform; new upstream property transformed automatically 2026-10-10
Transform is byte-exact outside property lines; CRLF fully preserved 76,551 CRLF, 0 bare LF; Terminal.h 1003 = 1003 2026-10-10
linscp tracks 0 WinSCP source files; only the submodule gitlink git ls-files 2026-10-10
Both targets build and pass 4/4 tests; Windows runs under Wine via CTest ctest on build/linux and build/win 2026-10-10
VCL surface the core needs: ~45 real types, dominated by UnicodeString (6,248), TStrings (521), Exception (438), TDateTime (250) census.py, resolved against real mingw/OpenSSL/stdlib headers 2026-10-10
Core’s Win32 headers (shlobj, psapi, winioctl…) are satisfied free on the mingw target only VCL needs shimming for Windows 2026-10-10
-fshort-wchar yields sizeof(wchar_t) == 2 on both linux-gnu and mingw32 static_assert compiled for both targets 2026-10-10
char_traits<wchar_t> really does call wmemcmp/wcslen/wmemchr; char_traits<char16_t> does not /usr/include/c++/14/bits/char_traits.h:512,522,534 2026-10-10
UnicodeString API scoped from measured use: IsEmpty 594, Length 444, c_str 247, SubString 184, Pos 86, Delete 79 grep over the generated core 2026-10-10
6/6 tests pass on Linux and on Windows under Wine, including UnicodeString ctest both build trees 2026-10-10
A real core TU compiles against the shim with 70 errors from 12 distinct missing VCL types (was 109 / 24) compile_census.py on core/Common.cpp, mingw target 2026-10-10
On the mingw target every remaining diagnostic is a VCL gap, not a platform one Win32 types all resolve via the real mingw headers 2026-10-10
7/7 tests pass on both targets after the byte-string family ctest 2026-10-10
Common.cpp down to 30 errors / 5 distinct missing types (from 109 / 24) compile_census.py 2026-10-10
10/10 tests pass on Linux and on Windows under Wine ctest both trees 2026-10-10
The ratchet detects a regression: baseline 25 against actual 30 fails simulated baseline, exit 1 2026-10-10
TDateTime matches Delphi’s four documented anchors, including -1.25 = 1899-12-29 06:00 test_datetime 2026-10-10
Delphi’s DayOfWeek offset verified independently against five known dates standalone cross-check, k=6 2026-10-10
Common.cpp: 109 -> 5 errors — superseded: the parse was aborting at a missing header see the correction above 2026-10-10
Upstream pinned to 6.5.8, the latest stable release git tag; 6.6.x is entirely RC/beta 2026-10-10
The transform handled the version change with no script edits: 624 declarations across 70 files, 0 unhandled transform.py on 6.5.8, which differs from the old pin by ~2,500 lines across 58 core files 2026-10-10
All 624 transformed declarations compile on 6.5.8 check_properties.py, exit 0 2026-10-10
Honest aggregate census: 2,409 errors across 9 core TUs, ratcheted census_ratchet.py 2026-10-10
12/12 tests pass on both targets after the version change ctest both trees 2026-10-10
All 44 __closure typedefs rewrite to TClosure<Sig>; 16 single-line, 28 spanning lines, 0 unhandled transform.py 2026-10-10
Changed lines now fully accounted for: 624 property + 44 closure + 28 template-end = 696 verify_transform.py 2026-10-10
CLOSURE() binds the enclosing instance correctly on both targets, including non-void returns and reference arguments test_closure on Linux and under Wine 2026-10-10
Aggregate census 2,409 -> 1,924 across 9 TUs; Terminal.cpp missing types 51 -> 20 census_ratchet.py 2026-10-10
116 call sites pass a bare member-function name where a closure is expected clang diagnostic count across all core TUs 2026-10-10
13/13 tests pass on both targets ctest 2026-10-10
core/Option.cpp compiles clean on mingw: exit 0, 0 errors, 0 fatal direct clang run, verified rather than inferred from the census 2026-10-10
The same TU still fails on Linux with 10 Win32-type errors the deferred P1-07 gap 2026-10-10
Aggregate census 1,924 -> 1,220 across 9 TUs census_ratchet.py 2026-10-10
Format handles width, alignment, precision and explicit argument indices; unknown specifiers and missing arguments stay visible instead of dropping text test_strutils 2026-10-10
161 narrow string literals in core require UnicodeString(const char *) grep over generated core 2026-10-10
14/14 tests pass on both targets ctest 2026-10-10
core/Option.cpp compiles clean on Linux and Windows: 0 errors each direct clang runs on both targets 2026-10-10
FILETIME conversions validated against the real Win32 API under Wine, using epoch anchors fixed by the format test_win32_posix on both targets 2026-10-10
Real Win32 FileTimeToSystemTime faults on a null argument; the POSIX version rejects it Wine crash dump, cmpq $0, (%rcx) 2026-10-10
Honest totals with 0 units aborting: mingw 1,334, Linux 1,575 census_ratchet.py, both targets 2026-10-10
15/15 tests pass on both targets ctest 2026-10-10
Census after streams: mingw 1,242, Linux 1,483, 0 aborting census_ratchet.py 2026-10-10
16/16 tests pass on both targets ctest 2026-10-10
Option.cpp and NamedObjs.cpp both compile clean on both targets compile_census.py, 0 errors each 2026-10-10
Census after containers: mingw 1,070, Linux 1,299, 2/9 units clean census_ratchet.py 2026-10-10
17/17 tests pass on both targets ctest 2026-10-10
Resource strings resolved with no core changes: 608 strings generated from upstream’s .rc, all ids matched, 0 unknown, 0 duplicates gen_resources.py 2026-10-10
18/18 tests pass on both targets ctest 2026-10-10
FileBuffer.cpp joins the clean set: 3/9 units at 0 errors on both targets compile_census.py 2026-10-11
Census after storage and arrays: mingw 963, Linux 1,182, 0 aborting census_ratchet.py 2026-10-11
TRegistry round-trips against the real Windows registry under Wine test_storage on the mingw target 2026-10-11
20/20 tests pass on both targets ctest 2026-10-11
Closure call sites: 62, not 118 — resolving macro-expansion diagnostics to their definitions collapsed the duplicates bind_closures.py --discover 2026-10-11
DynamicArray::Length is a read/write property, not a method; 56 of the original 118 reports were this, not closures Buffer.Length = 10*1024 in core 2026-10-11
All 758 changed lines accounted for: 624 property + 44 closure typedef + 28 template end + 62 binding verify_transform.py 2026-10-11
Census after closure binding: mingw 933, Linux 1,152 census_ratchet.py 2026-10-11
21/21 tests pass on both targets ctest 2026-10-11
Census after the long tail: mingw 619, Linux 863 (from 933 / 1,152) census_ratchet.py 2026-10-11
Every __closure in core converted: 44 typedefs, 2 inline parameters, 62 bound sites transform.py, 0 remaining 2026-10-11
22/22 tests pass on both targets ctest 2026-10-11
Census after the property-access fix: mingw 342, Linux 586; 4/9 clean on mingw census_ratchet.py 2026-10-11
Borland’s __property reaches private accessors; __declspec(property) does not TBookmark declares public properties over private setters 2026-10-11
__finally in core: 182 blocks, 0 __try, 0 __except; only 2 bodies contain a return grep plus brace analysis 2026-10-11
UnicodeString has implicit numeric constructors in C++Builder EXT_EXCEPTION_METHODS calls ExtException(E, Ident) with an int, and the only viable overload takes a string 2026-10-11
All 179 try/__finally blocks transformed, 0 unhandled; the patch series is still empty transform.py 2026-10-11
Changed lines: 1,297, every one accounted for — 624 property, 46 closure, 28 template end, 62 binding, 537 try/finally (179 x 3) verify_transform.py 2026-10-11
Census after try/finally: mingw 314, Linux 496; 4/9 clean on both targets census_ratchet.py 2026-10-11
23/23 tests pass on both targets ctest 2026-10-11
FileMasks.cpp clean on both targets; 5/9 units clean on both compile_census.py 2026-10-11
Census: mingw 266, Linux 441 census_ratchet.py 2026-10-11
Vendored expat compiles for both targets; the mingw sysroot has no expat cmake/expat.cmake 2026-10-11
The Windows CRT’s towlower folds only ASCII in the default locale the same test run against the real CRT under Wine 2026-10-11
24/24 tests pass on both targets ctest 2026-10-11
12/12 tests pass on Linux and on Windows under Wine ctest both trees 2026-10-10
Directory search validated against both backends: real FindFirstFileW under Wine, and dirent + fnmatch on Linux test_sysutils on both targets 2026-10-10
__closure scope: 44 distinct closure types, 16 typedefs; call sites pass bare member-function names grep over generated core 2026-10-10

Task status

P0 — Foundation

ID Task Status Note
P0-01 Repo layout done port/{shim,platform,tools,patches}, qt/, cmake/
P0-02 Pin submodule to a release tag done 6.5.8, latest stable; 6.6.x is all RC/beta
P0-03 Dual-target property macro header done port/shim/vcl_property.h; 9 forms, self-tested
P0-04 Verify C++Builder accepts the macro blocked Q-2: needs licence + Windows
P0-05 transform.py property rewriter done 613/613, 0 unhandled
P0-06 transform.py fastcall/ARRAYOFCONST done __closure handled by P0-06b/c/d
P0-06b __closure type + typedef transform done 44 typedefs; CLOSURE() macro verified on both targets
P0-06c __closure call-site binding done 62 sites; verified as a test
P0-06d __closure inline parameter form done 2 sites in SessionInfo
P0-07 Transform idempotence tests done idempotent + line-count parity asserted
P0-08 CMake skeleton done transform+verify wired as a build step; CTest on both targets
P0-09 Minimal shim for core/Common.cpp wip 224 errors; Option.cpp is the first TU at 0
P0-10 mingw-w64 sysroot + clang toolchain file done cmake/toolchain-mingw-w64.cmake; clang + lld + Wine emulator
P0-11 CI matrix Linux + Windows cross todo
P0-12 Wine smoke tests in CI wip wired into CTest via CMAKE_CROSSCOMPILING_EMULATOR; GitHub Actions pending
P0-13 Golden-output harness todo highest leverage in P0
P0-14 Protocol server containers todo
P0-15 Capture golden corpus from real WinSCP blocked Q-2: needs Windows host
P0-16 ADR log wip doc/qt/adr/ started with ADR 0001
P0-17 Property compile-check harness done check_properties.py, 613 declarations, clang exit 0
P0-18 HTML render of plan docs done doc/qt/plan.html via build-html.sh
P0-19 Publish repository, licence, root README done public at 99ecarvalho/linscp; work on qt
P0-20 Fork-branch generator todo deferred to P1-19 (Q-7); rehearsed manually in P0-22
P0-21 verify_transform.py upstream-diff audit done asserts line parity, byte-exactness and 1 macro per changed line
P0-22 Rehearse history import into a winscp fork done zero-conflict merge; 613-line in-tree diff; mechanical conflict resolution
P0-23 check_docs.py TASKS/TRACKER consistency done found 3 drifts on first run
P0-24 VCL surface census done ~45 types; build/shim_spec.txt
P0-25 ADR 0001 character width done accepted: -fshort-wchar + std::u16string
P0-26 check_wide_abi.py ADR enforcement done shim_no_wide_abi test
P0-27 compile_census.py done classifies clang diagnostics into shim gaps
P0-29 Legacy unqualified RTL header stubs done Classes.hpp etc.; absence was aborting most TUs
P0-30 Win32 A/W macro collisions undone done link-time guard test
P0-31 Ratchet both targets, track aborts done an abort is a distinct state, not a low number
P0-32 port/compat for upstream gaps dropped help.h was compensating for the missing WINSCP define; withdrawn 2026-10-11
P0-28 census_ratchet.py done both targets; aborts tracked separately

P1 — Headless core

ID Task Status Note
P1-01 Shim: UnicodeString class done 1-based API, UTF-16, 9 test groups incl. surrogate pairs
P1-01b Shim: free string routines done Option.cpp reaches 0 errors
P1-01d Shim: TVarRec/Format/ARRAYOFCONST done FORMAT 438 + FMTLOAD 252 call sites
P1-01e Resource strings done 608 strings generated from upstream .rc; no core changes
P1-01c Shim: byte-string family + UTF-8 codec done malformed-input behaviour tested explicitly
P1-02 Shim: TObject/TStrings/TStringList done 0-based indexing, case-insensitive default, CommaText round trip
P1-02b Shim: TList/TObjectList/sets done ownership and Notify semantics tested
P1-03 Shim: TDateTime + date/time RTL done documented anchors, negative composition, FormatDateTime
P1-03b Shim: SysUtils/IOUtils/StrUtils paths done everything core calls from those units compiles for Windows; POSIX file calls are P1-07b
P1-04 Shim: exceptions done 17 Delphi classes; base and sibling matching tested
P1-05 Shim: TCriticalSection/SyncObjs done recursive; thread exclusion tested
P1-05b Shim: TThread/StartThread done Win32 threads, events and waits on POSIX; BeginThread/EndThread on both. Tested against the real kernel under Wine. TThread itself dropped — dead upstream
P1-08b Shim: masks, paths, timespan, encoding, env done the census long tail
P1-08c Shim: XML DOM over expat done real parsing; FileZilla-shaped fixtures
P1-07c port/platform wide-char functions done ASCII folding, matching the Windows CRT
P1-09b try/__finally for POSIX done 179 blocks, 0 unhandled; same expansion on both targets
P1-06 Shim: streams done TStream/THandleStream/TFileStream/TMemoryStream
P1-06b Shim: INI/registry storage done INI parses real-world files; registry real on Windows
P1-06c Shim: DynamicArray + file API done sharing semantics tested
P1-06d Select INI backend on Linux todo frontend decision
P1-07 port/platform Win32 subset done types, FILETIME/SYSTEMTIME, errors, winsock names
P1-07b port/platform Win32 file/handle functions todo as the census asks
P1-08 Socket-event emulation todo R6
P1-09 PuTTY unix backend re-import todo
P1-10 PuTTY delta reconciliation todo
P1-11 FileZilla MFC subset replacement todo
P1-12 FileZilla epoll rewrite todo R2 — budget generously
P1-13 System libs wip PuTTY and its MSVC-built crypto build for Windows from the submodule; neon, OpenSSL, libs3 next
P1-14 Drop puttyvs done the MSVC build is replaced by clang building the same files with the same defines, from PuTTYVS.vcxproj
P1-15 Console IPC → stdio todo
P1-16 Headless Interface.h frontend todo
P1-17 First SFTP session on Linux todo long tail expected
P1-18 Windows cross-build + Wine todo
P1-19 Golden suite green, both platforms todo P1 gate
P1-20 .NET assembly drives Linux CLI todo
P1-21 #ifdef out Windows-only subsystems todo

P2 — Qt shell

ID Task Status Note
P2-01 Qt6 for mingw todo R4
P2-02 Qt app skeleton todo
P2-03 Qt Interface.h implementation todo
P2-04 Site manager todo
P2-05 Login/auth dialogs todo
P2-06 Remote file panel todo
P2-07 Transfer + queue UI todo
P2-08 Local file panel todo
P2-09 i18n pipeline todo do early
P2-10 Packaging todo
P2-11 P2 exit gate todo

P3 — Qt parity

ID Task Status Note
P3-01 .dfm → .ui converter todo
P3-02 Commander dual-pane todo the main draw
P3-03 Synchronization UI todo
P3-04 Preferences todo XL — split first
P3-05 Internal editor todo Q-3
P3-06 Remaining 48 dialogs, batched todo XL — split into P3-06a…f
P3-07 Drag & drop todo
P3-08 Shell integration todo
P3-09 Accessibility todo
P3-10 P3 exit gate todo

P4 — Cleanup

ID Task Status Note
P4-01 Retire VCL frontend todo
P4-02 Collapse dual-target #ifdefs todo
P4-03 Fold generated tree into source todo optional, one-way door
P4-04 De-shimming evaluation todo recommendation: do not

Estimates

Assumptions

Where AI actually multiplies — and where it does not

The multiplier is highly uneven across this project, and the uneven parts are what the estimate turns on.

Strong fit (3–8×)

Work Why
transform.py (P0-05/06) Mechanical, 4 regular forms, immediately self-testable by re-running
VCL RTL shim (P1-01…06) Well-specified APIs, a maintained reference to crib from (Far-NetBox src/base/), and unit-testable in isolation. The single largest chunk of P1 is also the best-suited
win32-on-posix (P1-07) ~40 functions with precise documented semantics
CMake / CI / toolchain files (P0-08…12) High boilerplate, fast feedback
PuTTY unix/ re-import (P1-09) Mostly reconciling two known trees
.dfm → .ui + dialog port (P3-01/04/06) .dfm is a declarative spec of layout, widgets, captions and tab order. This is the biggest single AI win in the project, and it sits in the most expensive phase

Moderate fit (1.5–2.5×)

Work Why
Qt Interface.h implementation, file panels, queue UI (P2-03…08) Real interaction logic and design judgment; AI drafts well, polish is human
Commander dual-pane semantics (P3-02) Deep keyboard-driven interaction behaviour users will notice immediately
First successful link (P1-17) AI is excellent per-fix, but the iteration count is high and each cycle is gated on a working build

Weak fit (1–1.5×)

Work Why
FileZilla epoll rewrite (P1-12) ~1,700 lines of subtle async state machine. Correctness is established by testing against real servers, not by reading code. Verification-bound
Protocol correctness (P0-15, P1-19) The FTP server zoo, SFTP extension quirks, S3 and WebDAV edge cases. Wall-clock bound by test infrastructure and real-world behaviour
C++Builder / Windows-native tasks (P0-04, P0-15) No local access; bound on a collaborator or licence
UX parity judgment Deciding what “parity” means is not a code task

Per-phase estimate

Phase Human (mo) + Opus 5 (mo) Multiplier Confidence
P0 Foundation 2 – 3 0.5 – 1.0 ~3–4× High — scope is well understood and the keystone is already tested
P1 Headless core 6 – 12 2.5 – 4.0 ~2.4–3× Medium — dominated by the shim (strong fit), dragged by P1-12 and P1-19 (weak fit)
P2 Qt shell 6 – 9 2.0 – 3.0 ~3× Medium
P3 Qt parity 18 – 36 6.0 – 12.0 ~3× Low — scope is undecided (Q-1) and this phase dominates the total
P4 Cleanup 1 – 2 0.25 – 0.5 ~4× High
Total 33 – 62 11 – 21 ~3×

One developer + Opus 5: roughly 11–21 months, against 2.8–5.2 years unassisted.

With a small team

P3 parallelises well — dialogs are largely independent — and P2 moderately. P0 and P1-17 do not parallelise much, being serialised on a single build bring-up.

Config Total
1 dev + Opus 5 11 – 21 months
3 devs + Opus 5 6 – 11 months

Compute cost

Unlike the rest of this document, this section is measured, not estimated. Every commit on the qt branch so far was produced by claude-opus-5, and the session transcripts carry per-turn token usage. Figures below are for the branch state at c801756 (2026-10-11): 22 commits, 16,960 lines added, 24 shim tests green on both targets, 5 of 9 tracked core units compiling clean on both.

Tokens consumed

Category Tokens
Base input 2,160
Cache writes (1h TTL) 1,922,665
Cache reads 473,255,696
Output (incl. reasoning) 1,654,640
Total 476,835,161

Cache reads are 99.2% of all tokens. That is the signature of this kind of work: a long-lived session re-reading a large working context (a 400k-line C++ tree, the shim, the plan docs) on every turn. It dominates the bill, so the cache-read rate — not the output rate — is what the cost turns on.

API price sheet

List prices per million tokens, from platform.claude.com/docs/en/about-claude/pricing as of 2026-10-11.

Opus 5 Opus 5.5
Base input $5.00 $4.00
Cache write, 5 min $6.25 $5.00
Cache write, 1 hour $10.00 $8.00
Cache read (hit/refresh) $0.50 (0.1× input) $0.20 (0.05× input)
Output $25.00 $20.00
Batch input / output $2.50 / $12.50 $2.00 / $10.00
Fast mode input / output $10.00 / $50.00 $8.00 / $40.00

Batch halves the base rates but is unusable here — the work is interactive and each step depends on the previous build result.

Cost of the work done so far

The same measured token mix, priced under both sheets:

Line item Opus 5 Opus 5.5
Base input $0.01 $0.01
Cache writes $19.23 $15.38
Cache reads $236.63 $94.65
Output $41.37 $33.09
Total $297.23 $143.13
Share of bill that is cache reads 80% 66%
Per commit (22) $13.51 $6.51
Per 1,000 lines landed $17.53 $8.44

Opus 5.5 is 52% cheaper on this workload, not the 20% the headline list price suggests. The reason is the cache-read multiplier: 0.05× base input instead of 0.1×, which on a session that is 99% cache reads is the only number that matters. Any workload shaped like this one — long sessions over a large fixed codebase — should expect the same disproportionate saving.

Caveat on reasoning effort: price per token does not vary with effort. Effort changes how many reasoning tokens are produced, not the rate they are billed at. So the Opus 5 column is a bill, but the Opus 5.5 column is this session’s token mix re-priced — not Opus 5.5 actually doing the work. If 5.5 reaches the same result in fewer tokens the real figure is lower; if it deliberates more, higher.

Extrapolated to completion

Progress is ~14% of the plan by month-weighted task completion (P0 26/35 and P1 18/36 against the per-phase Opus 5 budgets above). Scaling the measured spend:

Scenario Plan progress Opus 5 Opus 5.5
Full parity, optimistic (11 mo) 19.8% $1,498 $722
Full parity, midpoint (15.9 mo) 13.7% $2,162 $1,041
Full parity, pessimistic (21 mo) 10.4% $2,860 $1,377
Narrow Qt client (Q-1), 8–14 mo 15–27% $1,090 – $1,907 $525 – $918

Order of magnitude only. The extrapolation assumes cost per unit of plan progress stays flat, and it will not: P3 generates Qt UI from .dfm declarative specs, writing more and searching a huge C++ tree less, so the cache-read share that dominates today should fall as the project moves into the UI phases.

Subscription seats are a different currency

The figures above are API list prices. On a Claude subscription seat (Pro, Max, or a Team / seat-based Enterprise seat) none of it is billed per token: usage is included up to the plan’s rolling 5-hour and weekly limits. Spend beyond those limits is only possible if usage credits (formerly “extra usage”) are enabled — on Team and seat-based Enterprise that is an Owner / Primary Owner decision, with optional monthly spend caps per organisation, per seat tier and per member. With credits disabled, hitting the limit pauses work until it resets; it cannot generate a surprise invoice. See Max plan limits and extra usage for Team and seat-based Enterprise plans.

The practical consequence for planning this port: on a subscription seat the limit is wall-clock throughput, not money. That reinforces the conclusion below rather than changing it.

The binding constraint

Code generation is not the bottleneck; human review and real-world verification throughput are.

This matters for planning:

Sensitivity

The estimate is dominated by one undecided question.

Variable Effect
P3 scope (Q-1) A deliberately narrower Qt client cuts P3 from 6–12 to ~3–5 months → total 8–14 months. This is the single largest lever in the plan
R1 fails (C++Builder rejects the macro) P0 +0.5 mo, and the zero-diff upstream story weakens — higher ongoing merge cost, not a higher build cost
R2 worse than expected (FileZilla rewrite) P1 +1–2 mo. Mitigation: ship SFTP/SCP/S3/WebDAV first and treat FTP as a later deliverable
No Windows host available P0-04 and P0-15 stay blocked; the dual-target guarantee becomes unverified and Windows releases cannot be certified

Honest caveats