Review guidance for Unpackerr

Longer runtime/API context: INTERNALS.md.

Unpackerr is a single-process daemon. One goroutine in Run() (pkg/unpackerr/start.go) owns the live Config, the queue map, and the folder tracker. HTTP handlers validate input and hand mutations to that goroutine through onMainLoop. Review with that model in mind; the items below have been raised and rejected before.

Concurrency

• Live Config fields are read and written only on the main loop. Do not ask for a mutex around u.StartDelay, u.Passwords, u.Sonarr, and similar. If a new reader runs on another goroutine, route it through onMainLoop instead. Exception: GET /api/stats / Prometheus Collect read Starr/folder map headers under configMu and the last poll snapshot under History.mu. Poll workers publish Queue and last* after GetQueue returns. Do not hop that path onto onMainLoop.
• retrieveAppQueues does not need to snapshot the app lists. A config PUT applies on the same goroutine, which is parked in wait.Wait() until every poll returns.
• syncFileUIPassword is not a lock-order inversion. uiPassword() releases uiPassMu before configMu is taken.
• Two administrators saving config at the same instant is not a design target. Do not propose snapshot-and-merge logic whose only purpose is concurrent PUTs.
• History.mu, histMu, configMu, and uiPassMu each guard one thing for HTTP readers. Do not suggest adding a fifth lock; suggest moving the work to the main loop.

Validation and input

• Starr URLs are checked for an http:// or https:// prefix, matching startup. Do not request url.Parse or a non-empty host.
• The history JSONL is written by this process, capped at keep_history, and read with bufio.Reader.ReadBytes. It is not untrusted input. Do not request line caps, bounded readers, atomic rename, rollback copies, or .bak handling for it. Starr and Folder rows newer than 72 hours are restored into History.Map after validateApps. Folder items are attached to the watch tracker after PollFolders (which replaces u.folders). Do not skip Folder rows.
• A local admin POST does not need context-cancellation checks between enqueue and execution on the main loop.
• New() allocates Config, Webserver, History, and folders. Nil checks on those fields in HTTP handlers are dead code.
• The tray builds its menus in readyTray before go u.Run(), and a config PUT cannot apply until the loop drains taskChan, so those reads of live Config are ordered before any possible write. They are not a race and do not need a lock.
• filepath: values are kept as written in fileConfig and expanded on the live copy only (expandFilepaths). PUT may add or change a filepath: string; a missing secret file is 400. Webserver PUT expands filepath: only on ui_password. Do not add expandFilepaths across API keys or TLS paths as a drive-by.

Tests

• Do not force a write failure with a read-only directory. The container image runs as root, which ignores the permission bits, and Windows ignores them outright. Use blockedPath, which puts the target under a regular file so the write fails with ENOTDIR for every user and platform.

Config PUT

• Sections that the loop cannot re-apply in place return restartRequired: true and set pendingRestart; the loop re-execs itself once the queue is idle (maybeRestart). Folders and listener/TLS/logger changes fall in this group. Do not request an in-process watcher or listener rebuild.
• General PUT resets the loop tickers directly; interval changes do not need a restart.