Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-full-r5.md

# LedgerBot - ops handover

Version 3.2.0 · Written 2026-10-23 · Escalation: RPA dev team, Teams channel **#rpa-support**

## 1. What the bot does

LedgerBot compares the daily bank statement (an Excel file) with the entries in **LedgerPro**, the desktop accounting app. You start it with one statement file. First it opens LedgerPro and clicks Export to get LedgerPro's current entries. Then it checks every statement line. If a line is in LedgerPro with the same amount (within 1 cent), it is OK. If the amount differs, it is a Mismatch, which the bot only reports and never corrects. If the line is not in LedgerPro, the bot **types it into LedgerPro and clicks Save**. At the end it writes one result Excel to the output folder.

The bot has **no window of its own**. You only ever see LedgerPro being driven, the mouse moving by itself, and the result file when the run ends.

## 2. How it works

```
launcher.exe  (what you start, with the statement file)
   ├─ checks the update server, installs a new build if there is one
   └─ starts → LedgerBot.exe (no window) ──drives──> LedgerPro desktop app
                    │                                (do not touch while it runs)
                    ├─ reads  → statement Excel you gave it
                    ├─ reads  → data\ledger_export.xlsx (LedgerPro's export)
                    ├─ writes → logs\ledger_<date>.log  (+ logs\notfound_<button>.png)
                    └─ writes → data\output\Reconcile_<date>_<time>.xlsx (at the very end)
```

- **launcher.exe** checks for updates, then starts the bot and closes. It writes nothing anywhere.
- **LedgerBot.exe** is the bot itself. It works LedgerPro by finding the buttons as pictures on the screen and clicking them.
- **LedgerPro** is the target app. The bot opens it from the LedgerPro shortcut on the Desktop.
- **ledger_export.xlsx** is LedgerPro's list of current entries, produced when the bot clicks Export.
- **The log** gets one line per statement line, plus a screenshot whenever a button could not be found.
- **The Reconcile file** is the result: one row per statement line, with the columns Reference, Amount, Result and Note.

**One run, step by step:**
1. The launcher checks for an update, then starts the bot with your statement file.
2. The bot opens LedgerPro and waits a fixed 15 seconds.
3. It clicks LedgerPro's **Export to Excel** button and waits a fixed 10 seconds.
4. It reads the export and your statement.
5. It goes through the statement line by line. A missing line is posted like this: click **New entry**, type the reference, press Tab, type the amount, click **Save**.
6. It writes the Reconcile file. **Nothing is saved to the Reconcile file until this last step.**

## 3. Before a run

- [ ] The **LedgerPro shortcut** (named `LedgerPro`) is on your Desktop or on the Public Desktop. If it is missing, the bot stops at once and leaves no message (E01).
- [ ] **Display scaling is 100% and the resolution is 1920 x 1080** (Windows Settings → System → Display). At any other setting the bot cannot find LedgerPro's buttons (E02, E05, E06). This also applies to a new laptop, an external monitor or a remote-desktop session.
- [ ] The **logs** folder and the **data\output** folder exist next to LedgerBot.exe. Without logs the bot does not start. Without data\output the bot does all the posting and then loses the result file (E12, E13).
- [ ] LedgerPro is closed, or at least has no half-filled entry form open.
- [ ] No Reconcile file from a run in the same minute is open in Excel.
- [ ] Statement file rules:
  - Use the **first sheet**, with row 1 as the header. Column A is the reference and column B is the amount. Data starts on row 2.
  - The **amount must be a real number**.
    - Good: `1250.50`
    - Bad: `1,250.50 USD`, `n/a`, or an empty amount cell next to a reference. Any of these stops the whole run with no message (E10).
  - **Each reference only once.**
    - Good: `TX-1001` on one row only.
    - Bad: `TX-1001` on two rows. The bot keeps only the last one and says nothing about the first (E09).
  - **Write each reference exactly as LedgerPro shows it.**
    - Good: `TX-1001`.
    - Bad: `TX 1001` or `1001`. These count as "not in LedgerPro", so the bot posts them a second time.
- [ ] To start the bot, **drag the statement file onto launcher.exe**, or use a shortcut that passes the file. If you start the launcher with no file, the bot stops at once and leaves no message (E14).
- [ ] You cannot check the version today, because the bot shows it nowhere (section 10).

## 4. During a run

- **Hands off the machine.** Don't touch the mouse or keyboard, and don't open other windows. The bot types into whichever window is in front. If another window comes forward, the reference and amount go into that window (E17).
- Don't click in LedgerPro and don't close it. Close any LedgerPro popups only after the run ends.
- **To stop the bot:** the bot has no Stop button and no window to close. Closing LedgerPro does **not** stop it. Use one of these:
  1. Move the mouse quickly into the **top-left corner** of the screen. The bot stops at its next click or keystroke.
  2. Or open Task Manager and end **LedgerBot.exe**.

  Either way, **no Reconcile file is written** for that run. Use the log to see what was already posted (E11).
- **How long it takes:** an OK or Mismatch line takes no time. A posted line takes up to about 40 seconds. When a button can't be found, the bot gives up on that line after 20 seconds.
- **A run looks stuck** when the log gets no new line for more than 2 minutes after the first line. The bot has no watchdog and never restarts by itself. Stop it as described above, then post in #rpa-support.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | Output folder `data\output`: there is a new `Reconcile_<date>_<time>.xlsx` with the time the run ended. **No new file means the run did not finish.** |
| Which lines failed or need a look? | The Reconcile file. Filter the **Result** column for `Error` and `Mismatch`, and also check `Missing` rows (section 6). |
| Why did one line fail? | The **Note** column of the Reconcile file. Then `logs\ledger_<date>.log`: search for the reference. |
| A button "not found" error | `logs\notfound_<button>.png` is a screenshot of the screen at the moment the button wasn't found. It only shows the **latest** failure for that button, because each new one overwrites it. |
| The run died with no Reconcile file | `logs\ledger_<date>.log`. Each line written there was already handled, including posted lines. If the log has no line for today, the bot stopped before it reached the first line (E01, E02, E03, E10, E13, E14). |
| Did the bot already retry? | It does not retry lines or runs. Its only retry is looking for a button again for 20 seconds (section 8). |
| Which version is running? | You can't see it today. Ask in #rpa-support (section 10). |

The log file holds every run of the same day, one after another. Use the time at the start of each line to tell runs apart.

## 6. Statuses

The Reconcile file has no colours. It is a plain Excel file. The **Result** and **Note** columns together give the status.

| Result | Note | Meaning | What ops does |
|---|---|---|---|
| `OK` | (empty) | The line is in LedgerPro with the same amount, within 1 cent. | Nothing. |
| `Missing` | `Posted` | **The line was not in LedgerPro, so the bot typed it in and clicked Save.** "Missing" here means "was missing, now posted". The bot does **not** check that the save actually worked. | **Needs follow-up.** Spot-check these entries in LedgerPro (E07). |
| `Missing` | `Not in LedgerPro - posting` | Posting started but the run crashed. You should never see this in a saved file. | If you see it, post in #rpa-support. |
| `Mismatch` | `LedgerPro has <amount>` | The reference is in LedgerPro, but with a different amount. **The bot changed nothing.** | **Needs follow-up.** Investigate and correct by hand (E08). |
| `Error` | `Button new_entry.png not found on screen` | The bot could not open a new entry form. Nothing was typed. | E05. |
| `Error` | `Button save_btn.png not found on screen` | **The reference and amount were typed, but Save was never clicked.** The form may still be open in LedgerPro. | E06. Act before re-running. |
| (no Reconcile file) | - | The run stopped before the end. | Section 5, last rows. |

The log uses the same words on each line: `<reference> <Result> <Note>`.

## 7. Exception catalogue

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | LedgerPro never opens. There is no Reconcile file and no log line for the run. | It looks for the `LedgerPro` shortcut on your Desktop, then the Public Desktop. If neither has it, it stops. | **Nowhere.** The message goes to no file. | System | Ops | Put the LedgerPro shortcut, named exactly `LedgerPro`, on the Desktop. Re-run. | The shortcut is there and it still happens. |
| E02 | LedgerPro opens but nothing is clicked. There is no Reconcile file and no log line, but there is a `logs\notfound_export_excel.png`. | It looks for the Export button picture for 20 seconds, then gives up and stops the run. | Screenshot `logs\notfound_export_excel.png` only. | System | Ops, then Dev | Check that scaling is 100% and the resolution is 1920 x 1080, and that LedgerPro opened fully, maximised, with nothing on top of it. Re-run. | It happens again with the right display settings. Send the screenshot. |
| E03 | The run stops right after Export. There is no Reconcile file and no log line. | It **does not check**. It waits a fixed 10 seconds after Export and reads the export file. If the file isn't there yet, is open in Excel, or is in a different place, the run crashes. | **Nowhere.** | System | Ops, then Dev | Close any open copy of the export in Excel and re-run once. LedgerPro may be slow, for example on first start. | It fails twice. Say the time and that no log line was written. |
| E04 | Lines that were already in LedgerPro show `Missing / Posted`, and LedgerPro now has the same entry twice. | It **does not check**. If Export did not produce a new file in time, the bot reads the previous export. | Reconcile file (rows look normal). | System | Dev | Remove the duplicate entries in LedgerPro if you can. Post in #rpa-support with the Reconcile file name. | Always. |
| E05 | `Error - Button new_entry.png not found on screen` | It looks for the New entry button picture for 20 seconds, then marks the line Error and moves on. Nothing was typed. | Reconcile file, Note column. Log line. `logs\notfound_new_entry.png`. | System | Ops | Check the display settings and whether a LedgerPro popup was covering the screen. Re-run: a fresh run checks the line again and posts it. | Several lines in a row, or it happens again on the re-run. |
| E06 | `Error - Button save_btn.png not found on screen` | It typed the reference and amount, looked for Save for 20 seconds, then marked the line Error and moved on. **The half-filled form stays open in LedgerPro.** The next lines' clicks and typing may land on that form. | Reconcile file, Note column. Log line. `logs\notfound_save_btn.png`. | System | **Ops** | **Before re-running**, look in LedgerPro (if you have access; if not, ask in #rpa-support). Cancel any half-filled entry. Then check that every line *after* the Error that says `Posted` really exists and is correct. Re-run only after that. | You can't check LedgerPro, or entries after the Error look wrong. |
| E07 | `Missing - Posted`, but the entry is not in LedgerPro or is wrong. | It **does not check**. "Posted" only means Save was clicked. A LedgerPro popup or validation message is not noticed. | Reconcile file (looks successful). | System | Ops, then Dev | Spot-check posted lines in LedgerPro after each run. Missing entries are posted again on the next run. | It happens more than once. Send the reference, the time and the Reconcile file name. |
| E08 | `Mismatch - LedgerPro has <amount>` | The reference is in LedgerPro, but the amounts differ by more than 1 cent. | Reconcile file. Log line. | Business | Ops | Find out which amount is right and correct LedgerPro or the statement by hand. The bot never fixes it. | Never, unless the amounts are actually equal. |
| E09 | A statement line has no row in the Reconcile file. | It keeps one row per reference. A repeated reference keeps only its last row, silently. | **Nowhere.** | Business | Ops | Make each reference appear once. Handle the dropped line by hand. | - |
| E10 | The run stops with no Reconcile file and no log line for the run. | An amount in the statement or in the export is not a number, or is empty, so the run crashes while reading. | **Nowhere.** | Business | Ops, then Dev | Check column B of the statement: numbers only, nothing blank next to a reference. Re-run. | The statement is clean and it still happens (the export may be the cause). |
| E11 | The run stopped halfway (crash, mouse in the corner, Task Manager). There is no Reconcile file, but the log has lines for today. | Results are only saved at the end, so everything already done is in the log only. | Log only. | System | Ops | Lines in the log marked `Missing Posted` were already typed into LedgerPro. A re-run is safe **only because** it exports LedgerPro again first: those lines will then show OK. Re-run once and compare. | The re-run shows the same lines as Posted again (duplicates). |
| E12 | The bot posted everything, but no Reconcile file appeared. | The output folder `data\output` is missing, so the save at the end fails. | Log only (all lines are there). | System | Ops | Create the `data\output` folder next to LedgerBot.exe. **Don't re-run blind.** The postings are done; use the log as the record. | The folder exists and it still happens. |
| E13 | Nothing happens at all when you start the bot. | The `logs` folder is missing, so the bot can't even start. | **Nowhere.** | System | Ops | Create the `logs` folder next to LedgerBot.exe. Re-run. | The folder exists. |
| E14 | Nothing happens. LedgerPro does not open. | The launcher was started without a statement file. | **Nowhere.** | Business | Ops | Drag the statement file onto launcher.exe. | - |
| E15 | A new release was announced, but the bot behaves as before. | It **does not report it.** If the update server can't be reached, including when the laptop doesn't trust the server's certificate, the launcher quietly runs the old build. | **Nowhere.** | System | Dev | Post in #rpa-support with the machine name. | Always, after every release, until the version can be seen. |
| E16 | After a release, nothing happens when you start the bot. | The update download or unzip failed. The launcher crashes and never starts the bot. | **Nowhere.** | System | Dev | Post in #rpa-support with the machine name and the time. | Always. |
| E17 | References or amounts typed into another window, such as an email or chat. | It **does not check** which window is in front. It types into whatever has focus. | **Nowhere.** | System | Ops | Stop the bot (section 4). Delete the stray text. Check in LedgerPro which lines are really posted. Re-run hands-off. | It happens with nobody touching the machine. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A LedgerPro button is not on screen yet | Looks again every second | 20 seconds per button | Export button: the run stops (E02). New entry or Save: that line is marked Error and the bot moves to the next line (E05, E06). |
| LedgerPro slow to open | Nothing. It waits a fixed 15 s. | 15 s | Usually E02. |
| Export slow | Nothing. It waits a fixed 10 s. | 10 s | E03 or E04. |
| Update server unreachable | Runs the build already installed | 10 s | Old version keeps running, with no message (E15). |
| Anything else | **No retries, restarts, watchdog or resume.** | - | Run stops. See E11. |

**So there is never a reason to wait for the bot to fix itself.** If no new log line appears for 2 minutes, it is not going to recover.

## 9. Known incidents

Newest first. The exact dates and versions are not recorded. The display-scaling incident matches a log from 2026-09-05.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Before 3.2.0 (latest fix) | The packaged bot could not find any button. | The button pictures were left out of the build. | Fixed by dev, but the build file in the repo still doesn't include them (section 13). If **every** run fails at Export right after a release, it is this. Post in #rpa-support. | No |
| Before 3.2.0, about 2026-09-05 | `Error - Button save_btn.png not found on screen` on some laptops. | The laptops ran at 125% display scaling. The button pictures only match at 100%. | Keep 100% scaling and 1920 x 1080 (section 3). After any Save error, clear the half-filled form first (E06). | Yes |
| Before 3.2.0 | Two laptops stayed on an old version after a release, with no error. | The launcher hid a certificate error from the self-signed update server and ran the old build. | It still hides it. After each release, ask dev to confirm every machine updated (E15). | Partly |

## 10. Releases and version check

- **How an update arrives:** every time launcher.exe starts, it asks the update server for the latest version. If that differs from its own, it downloads the new build and unpacks it over the bot's folder. Then it starts the bot.
- **How to confirm it applied:** **you can't today.** The bot has no window and shows its version nowhere. After each release, post in #rpa-support with your machine name and ask dev to confirm the version.
- **If the version did not change:** don't copy files by hand. Post in #rpa-support. Dev must check the certificate and the download on that machine (E15, E16).
- Every machine reads and writes only its own files, so a machine on an old build doesn't damage the others. It can still behave differently, though, so keep all machines on the same version.

## 11. Escalating to dev

Post in **#rpa-support** (Teams). Send:
- the exception ID from section 7 (for example "E06")
- the machine name and the time of the run
- the Reconcile file name, or "no Reconcile file"
- the log file `logs\ledger_<date>.log` (attach it, don't paste lines)
- `logs\notfound_<button>.png` if there is one

**Never send:** passwords, the `.env` or any settings file, or statement or ledger contents (references, amounts, payee names) pasted in chat. The log can contain payee names, so share it as a file in the channel only, never outside it.

## 12. Failure-class check

- **F1** (missing prerequisite) is covered in section 3 and E01, E12, E13, E14, and in section 13 items 8 and 12.
- **F2** (wrong window / focus) is covered in section 4 and E17. The bot never brings LedgerPro to the front itself (section 13 item 11).
- **F3** (target app slower or different) is covered in section 3 (scaling and resolution), E02, E03, E05, E06 and section 8. The fixed waits are section 13 item 6.
- **F4** (input read differently) is covered in section 3 (the statement rules), E09, E10 and E14.
- **F5** (marked done when nothing was done) is covered in E07 and section 13 item 2.
- **F6** (action happened but not confirmed) is covered in E06 and E07 and section 13 items 2 and 3.
- **F7** (needs follow-up shown as success) is covered in section 6 (`Missing - Posted`) and section 13 item 1.
- **F8** (endless re-runs / watchdog): partly not applicable, because the bot has no auto-rerun and no watchdog (section 8). One possible update loop is section 13 item 10.
- **F9** (stopping the wrong way) is covered in section 4 and E11.
- **F10** (one stuck item blocks the queue): not applicable as a queue, because there are no batches or locks and each run is independent. The one blocking case, a half-filled form left open, is E06.
- **F11** (cause hidden from ops) is covered in section 13 items 4, 5 and 7.
- **F12** (update didn't arrive) is covered in section 10, E15, E16 and section 13 items 9, 10 and 12.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | Posted lines keep Result `Missing` (Note `Posted`), and the summary counts them as Missing. | Ops can't tell "posted" from "still missing" by Result alone. | `app.py:87-93` |
| 2 | Nothing confirms the save. "Posted" is written right after the Save click, and LedgerPro popups or validation are never detected. | An entry that was never saved shows as posted (F5/F6). | `app.py:65-70`, `app.py:90` |
| 3 | When Save is not found, the typed form is left open and the bot goes on to the next line. | Later lines can be typed into the leftover form, and the results after an Error can't be trusted. | `app.py:65-70`, `app.py:91-92` |
| 4 | Run-level failures write nothing to the log or the output: no shortcut, Export not found, export missing or bad, bad statement amount, no statement file given. | Ops sees "nothing happened" with no reason (E01-E03, E10, E13, E14). | `app.py:34`, `app.py:77-81`, `app.py:101` |
| 5 | Results are saved only at the very end. Any crash loses the whole Reconcile file, even though entries were posted. | The only record is the log (E11, E12). | `app.py:96` |
| 6 | Fixed waits of 15 s and 10 s, and no check that the export file is fresh. The docstring says the bot saves the export, but the code only clicks Export. | Slow LedgerPro means crashes or duplicate postings from yesterday's export (E03, E04). | `app.py:50`, `app.py:76-79` |
| 7 | The run summary goes only to the console, which the launcher discards. The not-found screenshot name has no time or reference, so each one overwrites the last. | Ops can't see the totals, and the evidence for earlier failures is lost. | `app.py:45`, `app.py:97`, `launcher.py:30` |
| 8 | `logs\` must already exist when the program starts. `data\` and `data\output\` are neither in the repo nor created by the code. | The bot won't start, or loses its output (E12, E13). | `app.py:24`, `app.py:96` |
| 9 | The launcher hides every update error, with no log. Download and unzip are unguarded. A version that is different but older is installed as an "update". There is no checksum. | Silent stale versions, a launcher crash after a bad release, or an accidental downgrade of every machine (E15, E16). | `launcher.py:19-20`, `launcher.py:25-29` |
| 10 | The launcher compares the server version against the version frozen into **its own** exe. If an update doesn't replace launcher.exe, every start may re-download. If the zip does contain launcher.exe, unpacking over the running exe can fail. Please confirm which happens. | Endless re-installs, or a crash on every start. | `launcher.py:9`, `launcher.py:25-29` |
| 11 | The version is shown nowhere. The comment claims a window title, but the bot has no window. There is also no Stop button, and nothing brings LedgerPro to the front before typing. | Ops can't verify releases, and stopping means Task Manager or the mouse-corner trick. | `app.py:15`, `app.py:65-70` |
| 12 | The build file in the repo is all comments. The "assets in the build" fix is not in it. Dependencies are not pinned. Newer versions of the screen-matching library raise an error instead of returning "not found", which would crash the run instead of marking the line Error. | The next build may ship without buttons, or behave differently from today's. | `ledgerbot.spec:2`, `requirements.txt:1-4`, `app.py:40` |
| 13 | Repeated references in the statement are dropped silently. | A line goes missing from the results with no trace (E09). | `app.py:52`, `app.py:81` |
| 14 | Display scaling and resolution are never checked at start. | A 125% laptop fails line by line instead of stopping with a clear message. | `app.py:20` |
| 15 | The 2026-09-05 log has a payee name on a Mismatch line. The current code doesn't write that, so the deployed exe may differ from this repo. | The repo may not be what is running, and logs may carry payee names. | `logs/ledger_20260905.log:3`, `app.py:60`, `app.py:95` |
| 16 | A `.env` file is committed, but no code reads it. It was not opened for this review. | Possible secrets in git. | `.env` |
| 17 | The `BOT_WAS_RUN` marker is written but never read or cleared. | Looks like run evidence, but it means nothing. | `app.py:74` |
| 18 | Ops access to LedgerPro is not confirmed. E06, E07 and E11 need someone to check entries in LedgerPro. | Without access, every Save error has to go to dev. | (process) |