Skip to content

fix: make a cold start work on a machine that already runs the project - #4

Merged
NanmiCoder merged 5 commits into
mainfrom
fix/cold-start-robustness
Jul 26, 2026
Merged

NanmiCoder merged 5 commits into
mainfrom
fix/cold-start-robustness

Conversation

@NanmiCoder

Copy link
Copy Markdown
Owner

Summary

Verified the README path end to end from a fresh clone — full 4.24 GB dataset from
GitHub Releases, both Skills installed with npx skills add -g, npm test / lint /
build / status all green. Three problems only appear once something else on the
machine holds a port, which is exactly the state a second checkout or a returning
user is in.

The printed URL could open a different application. Vite's default host
localhost resolves dual-stack, so with IPv4 127.0.0.1:5173 already taken it
still bound [::1]:5173, skipped its port-increment path, and printed
http://localhost:5173/. That URL served the unrelated app on IPv4, silently.
Binding 127.0.0.1 explicitly makes the collision visible.

before  ➜ Local: http://localhost:5173/   → <title>Field Notes · Todo</title>
after   Port 5173 is in use, trying another one...
        ➜ Local: http://127.0.0.1:5174/   → <title>Open Image Prompts …</title>

The Skill gallery could not start at all in a second checkout. Port 4173 was
fixed with no fallback, server_status only inspects the current checkout's
.oip/, and although the bind failed instantly the parent waited the full 30 s
before printing a traceback whose real cause was on the last line.

before after
default port taken 30 s → traceback → fail 1.25 s, falls back, url_usable: true
explicit port taken same 0.06 s, names the owner, suggests lsof

stdout stays pure JSON; notices go to stderr.

Abandoned galleries leaked forever. The process is detached on purpose, so a
session ending without stop never reaped it — this machine had a proxy plus two
Vite servers alive four days later, and they were what held 4173. Added an idle
watchdog (four hours, OIP_GALLERY_IDLE_TIMEOUT); health probes deliberately do
not count as traffic.

Plus the drift these gaps hid: both READMEs quoted 15,033 prompts / 25,216 images
against an actual 14,693 / 24,479; three files still pointed at a Git LFS corpus
that no longer exists; .dockerignore missed images/ and db/*.db.gz, shipping
4.3 GB of build context; and windows-start-smoke.yml was the only workflow, with
a paths filter that excluded skills/** and scripts/** — so none of this could
have been caught.

  • scripts/verify_docs.py reconciles prose counts against data/public-corpus.json,
    rejects stale LFS wording, and requires every style card to expose a unique id.
    No database, no network.
  • 17 cards whose heading was their id now carry an explicit id bullet, so all 39
    are read the same way.
  • AGENTS.md for an agent handed only the repository URL.
  • Docker build context: 4,336 MB → 1.6 MB.
  • tar.extract filter pinned (warns on 3.12/3.13, changed in 3.14), guarded so
    Python 3.10.0 still works.

Test Plan

  • npm test (docs, public-data boundary, API, gallery ports, 72-query
    retrieval benchmark, frontend), lint, build, status — green on a
    checkout with the full 24,479-file corpus
  • Retrieval benchmark unchanged: precision_on_returned 0.9567
  • Frontend collision: occupied IPv4 127.0.0.1:5173, confirmed the printed
    URL serves this app and nothing bound [::1]:5173
  • Gallery: fallback, fast failure on an explicit busy port, JSON-only stdout,
    gallery page and session JSON reachable on the fallback port
  • Idle watchdog both directions: exits when idle (children reaped, pid file
    removed); stays alive under periodic traffic
  • No Docker regression: OIP_WEB_HOST=0.0.0.0 still binds *:4193 and prints
    a network URL; strictPort fails loudly instead of drifting
  • verify_docs.py fails on an injected wrong count and on a removed card id
  • Fresh clone: ./start.sh completes all four steps unattended
  • docker build / docker run not executed — no Docker daemon available on
    this machine. The .dockerignore fix is measured statically.

Vite's default host is `localhost`, which resolves dual-stack. When another
process already held IPv4 127.0.0.1:5173, Vite still bound [::1]:5173, skipped
its port-increment path, and printed http://localhost:5173/ - a URL that opened
the other application with no error anywhere.

Bind 127.0.0.1 explicitly so the collision is visible and Vite moves to the next
free port. An explicit OIP_WEB_PORT is now strict, because Docker, CI and shared
links depend on that exact port.
The gallery port was fixed at 4173 with no fallback, and server_status only
inspects the current checkout's .oip/, so a second checkout on the same machine
reported "stopped" and then failed to bind. The bind failed instantly but the
parent still burned the full 30s timeout before printing a raw traceback with the
real cause on the last line.

Probe the port first: fall back to a free port when 4173 is taken and no port was
requested, and fail immediately with the owning process named when one was. The
gallery URL now carries the port actually bound. Startup also detects a dead child
instead of waiting out the timeout.

The gallery is detached on purpose, so an agent session that ends without calling
`stop` used to leak it forever - this repository had a proxy plus two Vite servers
alive four days later, holding 4173. Add an idle watchdog defaulting to four
hours, overridable through OIP_GALLERY_IDLE_TIMEOUT. Health probes do not count as
traffic, so a monitor cannot keep an abandoned gallery alive.

Also drop the Git LFS wording from the missing-dependency error and tell a Skill
installed outside a checkout where to get the repository.
.gitignore excludes images/ and db/prompts.db.gz but .dockerignore only excluded
db/*.db, so a checkout that had run `npm run data:pull` shipped 4.3 GB to the
Docker daemon on every build. The build re-fetches the archive itself, so neither
path belongs in the context. Measured on a full checkout: 4,336 MB down to 1.6 MB.

Also pin the tar extraction filter instead of relying on the default, which warns
on Python 3.12/3.13 and changed in 3.14. tarfile.data_filter exists exactly in the
versions that accept the keyword, so this stays compatible with 3.10.0.
Both READMEs quoted 15,033 prompts and 25,216 images while the released dataset
has 14,693 and 24,479, and three files still told readers to obtain a Git LFS
corpus that no longer exists. Nothing guarded either claim.

Add scripts/verify_docs.py, which reconciles the prose counts against
data/public-corpus.json, rejects stale LFS instructions, and requires every style
card to expose one unique id. It needs neither the database nor the network.

Give the 17 cards whose heading is their id an explicit id bullet too, so all 39
cards are read the same way, and say so in the Skill: a heading is not a reliable
id when six files use a prose title instead.

AGENTS.md is the condensed entry point for an agent handed only the repository
URL: how to start, where the dataset comes from, why no port may be hardcoded,
the Skill contract, and what to run before committing.
…pm test

windows-start-smoke.yml was the only workflow, so start.sh, npm test, lint and
build never ran in CI. Its paths filter also omitted skills/**, scripts/** and
tests/**, which is how the stale dataset counts and LFS instructions survived
review.

Add a Ubuntu and macOS matrix that runs start.sh and asserts the frontend answers
on the loopback address the launcher was told to use - a dev server that bound
another interface would pass a plain "did it start" check while serving nobody -
plus a Ubuntu job running the full suite, lint, build and Skill readiness.

Broaden the Windows paths filter to match, and add verify:docs and test:gallery to
npm test. Both run without the database, so they fail before the 80 MB download.
@NanmiCoder
NanmiCoder merged commit 9f4f5a2 into main Jul 26, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant