Add frozen CTF timer behavior and docs updates

[madebygps]

• Persist ctf_end_time on first successful export after 18/18
• Reuse frozen elapsed time in verify time and export output
• Clarify example flag and timer behavior in MOTD and READMEs
• Add timer behavior checks to CTF test script

resolves #79

[madebygps]

The Problem

@madebygps opened issue #79 with a simple but important concern: the CTF timer might not be telling the truth. Specifically, she was not confident that verify time accurately reflected how long a learner had actually spent on the challenges, especially for students who did not complete the lab in a single sitting.

Investigation

The session started with a deep read of the existing implementation in ctf_setup.sh. The time tracking turned out to be straightforward: a start timestamp written to /var/ctf/ctf_start_time on the first numeric verify command, and every subsequent verify time call doing a simple subtraction from that start to the current clock. As she put it: "verify time is just a subtraction essentially."

But that simplicity was also the problem. Walking through the code together, she identified the key gap: "We control when the time keeping starts with init_time but not when it stops." A learner who completed all 18 challenges on Tuesday, then came back Thursday to run verify export, would see their completion time include those two idle days. And if the VM was powered off in between, that offline time counted too.

Along the way, she caught an error in an early explanation. When it was incorrectly stated that init_timer was called on every verify command, she pushed back immediately: "Review the code and adjust your explanation." On closer inspection, init_timer is only called in the numeric challenge branch, not on verify time, verify progress, or other subcommands. That precise correction shaped how carefully the rest of the investigation proceeded.

There was also a related issue hiding in the progress counting: the example flag (verify 0 CTF{example}) counts toward the 18/18 tally, meaning learners who skip it can end up stuck at 17/18 without understanding why.

Decisions

Rather than tracking active keyboard time across sessions, which would require a daemon or stateful accumulator, she decided to keep wall-clock semantics but document them clearly and add a meaningful stop point: "I think we document that it is wall clock time from capture of first flag to capture of last flag and implement a completion_time_file or stop_time."

The freeze point would be the first successful verify export after all 18 challenges are done. After that, verify time and verify export both show the same frozen number no matter when they are run. File-based storage was the obvious choice, consistent with how progress is already persisted in /var/ctf. The example flag concern would be addressed through documentation only, with no logic changes.

Implementation

The core change was a new get_elapsed_seconds() helper that became the single source of truth for elapsed time in both verify time and verify export. It reads from /var/ctf/ctf_start_time and, when present, /var/ctf/ctf_end_time, otherwise falling back to the current clock. A new freeze_end_time_on_export() function writes that end file once, the first time verify export is called after 18/18 completion. This replaced two places in the code that previously each computed their own elapsed math independently, improving both correctness and DRY adherence.

The MOTD was updated to explain the example flag requirement and timer behavior clearly. Documentation was updated across all four READMEs: the root README got a dedicated timer and progress behavior section, the AWS and Azure READMEs gained a note that stopped VM time still counts toward elapsed until the timer is frozen, and GCP got a consistency note. Targeted timer tests were added to .github/skills/ctf-testing/test_ctf_challenges.sh covering the pre-start message, timer start trigger, and frozen elapsed behavior after export. Shell validation was confirmed clean with shellcheck -S warning -e SC1091 -e SC2086.

Resolution

Six files changed across ctf_setup.sh, all four READMEs, and the test script. The session cost an estimated $6.43 USD in AI usage across gpt-5.3-codex and claude-sonnet-4.6, based on GitHub Copilot published token pricing at 1 AI credit = $0.01.