feat: opt-in lists + notebook leg, so workspaces can delegate run_smoke.py

[Jammy2211]

Summary

Both PyAutoHands legs of #260 — collapsing the ten vendored
.github/scripts/run_smoke.py copies onto this runner.

The obstacle to delegation was never behaviour, it was discovery model.
run_python.py / run.py were opt-out only (recursive discovery minus
no_run.yaml), while the workspace and workspace_test variants are opt-in
allowlists (smoke_tests.txt, smoke_notebooks.txt). That mismatch is why seven
repos still vendor a copy of the loop, and why each of the last three fixes —
env resolution (#185), per-script timeouts (#226/#227), the jupyter guard — had
to be swept across N repos by hand. The HowTo tier needed none of those sweeps
because it holds no logic.

This PR gives Hands everything those seven repos need to become HowTo-shaped
delegators. No workspace changes here — those are one-file PRs that follow,
gated on this merging.

Measured 2026-08-24: ten copies, three variants, and no live drift inside any
variant. That is the receipt for three manual sweeps, not evidence the
copy-per-repo design is safe.

API Changes

Additive only; every existing call site behaves exactly as before.

• build_util.files_from_list(directory, list_path) — new; resolves an opt-in
  allowlist.
• build_util.regenerate_notebook(nb_path, scripts_dir) — new; stale-notebook
  recovery.
• execute_scripts_in_folder(..., files=None) and
  execute_notebooks_in_folder(..., files=None, write_back=True, retry_from_scripts=None)
  — new keyword args, defaults preserve today's behaviour.
• execute_notebook(..., write_back=True, retry_from_scripts=None, report_as=None)
  — new keyword args; now returns "passed"/"failed"/"timeout" instead of
  None. Split internally into _run_notebook_once + a wrapper owning the temp
  copy and the retry.
• CLI: run_python.py --list; run.py --list --no-write-back --retry-from.

See full details below.

Test Plan

• pytest tests/ -q → 388 passed, 5 skipped, 0 failed
• 16 new tests (tests/test_script_list.py, tests/test_notebook_delegation.py)
• The 38 existing notebook + timeout tests pass untouched, which is what
  makes the execute_notebook split safe
• Tenant-firewall gate (repos_sync.py --check --only "tenant firewall (organ code)") → OK
• Both CLI legs exercised end-to-end against fixture workspaces, not only via
  unit tests: allowlist order preserved; no_run winning over the list;
  a stale notebook recovering via regenerate-and-retry and being recorded
  once under its original path; a missing entry failing without stopping
  the run; the committed notebook byte-identical afterwards; exit codes
  propagating (1 with a failure, 0 all-green, 1 on a missing list file)

Readiness gate: PyAutoHeart is not checked out in the authoring session, so the
documented fallback applied — the repo's own suite as the gate, green.

Full API Changes (for automation & release notes)

Added

• build_util.files_from_list(directory, list_path) — resolves an opt-in
  allowlist to List[Path], in the list's own order. Blanks and # comments
  dropped, duplicates collapsed to first occurrence. Raises FileNotFoundError
  if the list file is missing.
• build_util.regenerate_notebook(nb_path, scripts_dir) — regenerates one
  notebook from its source .py into a temp dir via py_to_notebook. Raises
  FileNotFoundError when there is no source script.
• run_python.py --list FILE, run.py --list FILE — opt-in coverage.
• run.py --no-write-back — execute a throwaway copy, leaving committed
  notebooks untouched.
• run.py --retry-from DIR — one regenerate-and-retry from the scripts dir.

Changed

• execute_notebook returns a status string rather than None. Nothing in-tree
  consumed the old None.
• execute_scripts_in_folder / execute_notebooks_in_folder accept files=.
  Omitted → unchanged recursive discovery.

Deliberate invariants (each pinned by a test)

1. Allowlist order is the file's, not find_scripts_in_folder's
   simulator-first sort. A hand-maintained list's sequence is the author's
   statement of what must run before what.
2. no_run.yaml wins over the allowlist, and is checked before existence —
   so an excluded-and-deleted entry is SKIPPED, not FAILED. Letting a list
   override an explicit exclusion would resurrect a script someone deliberately
   turned off.
3. A listed-but-missing entry is one FAIL and the run continues. The
   runner's contract is to continue through failures; a stale entry must not cost
   coverage of every entry after it.
4. A missing list file is a hard error. Exiting 0 having tested nothing is
   the vacuously-green-gate failure mode.
5. A TIMEOUT is never retried — a second full cap buys the same answer and
   doubles the slowest entry's cost.
6. A clean skip-guard exit is already a PASS and never reaches the retry.
7. The retry's verdict replaces the first attempt's, so one notebook
   contributes exactly one result and a temp path never leaks into the report.

Two findings that changed the plan

• run_notebook.py writes executed outputs back in place. Right for
  generation, where the outputs are the product; wrong for a PR gate, which
  must not dirty the tree it is testing. Hence --no-write-back. Since the
  kernel cwd is already pinned to the repo root, this supersedes the
  workspace copy's staged-copy-at-root trick rather than porting it.
• JUPYTER_MISSING_RC did not need promoting. That guard exists because the
  workspace copy shells out to a bare jupyter, so an absent toolchain raised
  FileNotFoundError out of main() and aborted with no summary line.
  execute_notebook invokes sys.executable run_notebook.py, which always
  exists — the failure mode is structurally absent here.

Docs

docs/internals.md was stale on its own inventory: it claimed "nine copies,
five distinct revisions — they have drifted" and omitted HowToFit. Replaced with
the measured three-variant table, the promotion history, and the direction of
travel. bin/autohands help run / help run_python document the new flags.

Generated by the PyAutoLabs agent workflow.

---

Generated by Claude Code