README.md

Session Timer Status

VS Code extension for Welld remote development pods. Reads ~/.session-timer and shows time remaining in the status bar. Also monitors the AWS EC2 instance metadata service (IMDSv2) to detect spot instance termination notices.

Status Bar Display

Condition	Display
On a spot instance, all clear	$(pass) $(clockface) NNhNNm
Not spot / IMDS unreachable	$(clockface) NNhNNm
< 60 minutes remaining	$(clockface) NNhNNm + warning background
< 30 minutes remaining	$(warning) NNhNNm + error background
Spot termination imminent	$(warning) NNhNNm + error background + pop-up
Session preserved indefinitely	$(clockface) ∞

Warning Pop-ups

• Session warnings fire at 30, 15, and 5 minutes remaining. Each threshold fires once per descent; reset above the threshold to re-arm it.
• A CRITICAL WARNING: Spot instance shutdown imminent! error pop-up fires as soon as a termination notice is detected via IMDS.

Spot Instance Monitoring

On activation the extension fetches the IMDSv2 token and checks instance-life-cycle. If the instance is spot, it starts a dedicated 5-second poll of spot/termination-time. When a termination time appears, it immediately fires the critical pop-up and overrides the session timer display with the countdown to shutdown.

The $(pass) checkmark will be absent for the first 1–3 seconds after the extension loads while the IMDS round-trip completes. This is expected.

Fails silently if IMDS is unreachable or the instance is not spot.

Testing with set-session

The pod environment provides a set-session shell function for manually setting the session expiry.

set-session HH:MM

Examples:

set-session 02:00   # set session to expire in 2 hours (green)
set-session 00:45   # ~45 minutes left (warning background)
set-session 00:30   # → 30-minute warning pop-up
set-session 00:15   # → 15-minute warning pop-up
set-session 00:05   # → 5-minute warning pop-up

The extension picks up changes almost immediately via fs.watch on ~/.session-timer (the once-per-minute poll is just a fallback).

To re-test a threshold after it has already fired, set the time back above it first — e.g. set-session 00:31 then set-session 00:30.

Testing Spot Termination

Two commands are available in the command palette (Ctrl+Shift+P):

• Session Timer: Simulate Spot Termination — sets a fake termination time 2 minutes out, fires the critical pop-up, and overrides the status bar display immediately.
• Session Timer: Reset Spot Simulation — clears the simulated state, re-runs the IMDS lifecycle check, and restores the checkmark if on a spot instance.

Development

• Open repository in GitHub Codespaces and press F5 to run the extension, or use the pod workflow below.

Remote Development in a Welld Remote Development Pod

The pod has fnm installed but no other special tooling. Run the bootstrap script once to get everything ready:

./bootstrap-welld-remote-dev.sh

This installs Node 20 (if needed), runs npm install, and prints the commands for your next steps:

npm run compile          # compile TypeScript once
npm run watch            # recompile on save (useful during dev)
npm run package          # build the .vsix

Versioning and release tags

Use npm version for release bumps so package.json and package-lock.json stay in sync:

npm version patch --no-git-tag-version   # 0.1.1 -> 0.1.2
npm version minor --no-git-tag-version   # 0.1.2 -> 0.2.0
npm version major --no-git-tag-version   # 0.1.2 -> 1.0.0

Or set an explicit version:

npm version X.Y.Z --no-git-tag-version

Then commit the change and push a matching vX.Y.Z tag. The tag push builds and publishes the .vsix through GitHub Actions.

Installing / updating the extension

Using ./install-local.sh from the terminal only writes the files to disk — you still need to reload the extension host for changes to take effect. The safest workflow that avoids being logged out of GitHub Copilot:

1. Package: npm run package
2. In the Extensions panel (Ctrl+Shift+X): find Session Timer Status → gear icon → Uninstall
3. Install from VSIX: ... menu (top-right of Extensions panel) → Install from VSIX... → select session-timer-status-X.Y.Z.vsix
4. Click Reload Required when prompted — this reloads only the extension host, not the full browser window, so Copilot stays authenticated.