Merge main into the api_v3 split, carrying the three fixes it would have dropped

main modified web_interface/blueprints/api_v3.py while this branch deletes it,
so git reports a modify/delete conflict. Resolving that by accepting the
deletion - the obvious move - would silently discard every api_v3.py change
merged since this branch forked. Three were:

  #560  the sudo diagnosis on /system/action  -> api_v3/system.py
  #557  the stale-reconciliation-findings filter -> api_v3/plugins.py
  #550  the deletion of dead _validate_time_range -> api_v3/__init__.py

All three were verified absent from the split beforehand: _sudo_hint_for,
_SUDO_NEEDS_PASSWORD and _drop_stale_reconciliation_findings appeared in zero
files, while _validate_time_range was still sitting at __init__.py:343 after
#550 removed it from main. Each is now ported to the module that owns the
affected route, and the dead function is gone.

Two further changes this surfaced:

- api_v3/__init__.py imported fcntl at module scope. fcntl is POSIX-only, the
  monolithic blueprint never imported it, and on this branch it made the whole
  api_v3 package unimportable off POSIX: the pristine branch cannot run its
  test suite on Windows at all - 14 collection errors interrupt the run. The
  import now happens inside _starlark_manifest_lock(), the only thing that uses
  it. Deliberately NOT degraded to a no-op lock off POSIX; that function's
  docstring describes a real lost-update race, and silently not locking would
  be worse than failing loudly on a platform that cannot drive the display.

- test/test_reconciliation_status_endpoint.py is new. #557's endpoint wiring had
  no test - only the pure still_unresolved() helper in src/ was covered, and
  that lives outside web_interface so it survived the split untouched. Losing
  the filter during this merge would therefore have been completely silent.
  Removing the filter call now fails three of its seven cases.

Suite on this merge: 115 failed / 4317 passed. main today: 105 / 4252. All 11
extra failures are in test_starlark_pixlet_routes.py and need POSIX file locks,
so they are Windows-only; on that same file the pristine branch shows 19 failed
plus 39 errors, so this is a large net improvement rather than a regression.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

web_interface/blueprints/api_v3/__init__.py

@@ -17,7 +17,6 @@ everything they need has to exist first.
 """
 from flask import Blueprint, request, jsonify, Response
 import contextlib
-import fcntl
 import json
 import os
 import re
@@ -340,19 +339,6 @@ def _validate_time_format(time_str):
         return True, None
     except (ValueError, TypeError):
         return False, f"Invalid time format: {time_str}. Expected HH:MM format."
-def _validate_time_range(start_time_str, end_time_str, allow_overnight=True):
-    """Validate time range. Returns (is_valid, error_message)"""
-    try:
-        start_time = datetime.strptime(start_time_str, '%H:%M').time()
-        end_time = datetime.strptime(end_time_str, '%H:%M').time()
-
-        # Allow overnight schedules (start > end) or same-day schedules
-        if not allow_overnight and start_time >= end_time:
-            return False, f"Start time ({start_time_str}) must be before end time ({end_time_str}) for same-day schedules"
-
-        return True, None
-    except (ValueError, TypeError) as e:
-        return False, f"Invalid time format: {str(e)}"
 def _git_current_branch(project_dir):
     """Current branch name, or '' when detached or git fails."""
     try:
@@ -1380,6 +1366,15 @@ def _starlark_manifest_lock():
     Callers should do their read, mutation and _write_starlark_manifest() call
     entirely inside the `with` block, mirroring the plugin's lock scope.
     """
+    # Imported here, not at module scope: fcntl is POSIX-only, and a top-level
+    # import made the whole api_v3 package unimportable on Windows -- which the
+    # monolithic blueprint never was, so the split would have broken local dev
+    # and the test suite there. Deliberately NOT degraded to a no-op lock off
+    # POSIX: the docstring above describes a real lost-update race, and silently
+    # not locking would be worse than failing loudly on a platform that cannot
+    # run the display anyway.
+    import fcntl
+
     _STARLARK_APPS_DIR.mkdir(parents=True, exist_ok=True)
     lock_fd = os.open(str(_STARLARK_MANIFEST_LOCK_FILE), os.O_CREAT | os.O_RDWR, 0o644)
     try:

web_interface/blueprints/api_v3/plugins.py

@@ -707,6 +707,35 @@ def reconcile_plugin_state():
             context=error.context,
             status_code=500
         )
+def _drop_stale_reconciliation_findings(unresolved):
+    """Re-check a stored reconciliation verdict against current state.
+
+    The verdict is a snapshot written once per run, and a run that could not
+    apply a fix also refuses to retry -- so a resolved condition was reported
+    indefinitely. Best-effort: any failure here returns the list untouched,
+    because showing a stale warning beats failing the endpoint.
+
+    The disk set is enumerated directly rather than through
+    _installed_plugin_ids(): this mirrors StateReconciliation._get_disk_state(),
+    whose verdict we are re-checking, and avoids triggering a discovery scan on
+    an endpoint the overview page polls.
+    """
+    try:
+        from src.plugin_system.state_reconciliation import still_unresolved
+
+        config_keys = set(api_v3.config_manager.load_config() or {})
+        installed = set()
+        plugins_dir = getattr(api_v3.plugin_manager, 'plugins_dir', None)
+        if plugins_dir:
+            for entry in Path(plugins_dir).iterdir():
+                if entry.is_dir() and (entry / 'manifest.json').exists():
+                    installed.add(entry.name)
+        return still_unresolved(unresolved, config_keys, installed)
+    except Exception:
+        logger.debug("[Reconciliation] Could not re-check stored findings", exc_info=True)
+        return unresolved
+
+
 @api_v3.route('/plugins/reconciliation-status', methods=['GET'])
 def get_reconciliation_status():
     """Return the result of the last startup reconciliation from /tmp status file."""
@@ -721,6 +750,8 @@ def get_reconciliation_status():
     try:
         with open(_recon_path) as _f:
             data = json.load(_f)
+        if data.get('unresolved'):
+            data['unresolved'] = _drop_stale_reconciliation_findings(data['unresolved'])
         return jsonify({'status': 'success', 'data': data})
     except json.JSONDecodeError:
         logger.exception("[Reconciliation] Failed to parse status file: %s", _recon_path)

web_interface/blueprints/api_v3/system.py

@@ -171,6 +171,33 @@ def check_for_update():
         logger.warning("check-update failed: %s", e)
         return jsonify(_update_check_failed(
             "Could not check for updates; see logs for details."))
+#: sudo's own wording when it needs a password it cannot ask for. The web
+#: interface runs unprivileged, so its systemctl/reboot/journalctl calls only
+#: work once scripts/install/configure_web_sudo.sh has granted NOPASSWD --
+#: which first_time_install.sh does not do. That makes this the common case on
+#: a fresh device, and "Action failed; see logs for details" named none of it,
+#: while the log viewer was broken for the very same reason.
+_SUDO_NEEDS_PASSWORD = (
+    'a password is required',
+    'no tty present',
+    'a terminal is required',
+)
+
+_SUDO_HINT = (
+    'Passwordless sudo is not configured for the web interface user, so this '
+    'action cannot run. Run scripts/install/configure_web_sudo.sh as that user, '
+    'then retry.'
+)
+
+
+def _sudo_hint_for(text):
+    """An actionable hint when `text` is sudo refusing to prompt, else None."""
+    lowered = (text or '').lower()
+    if any(marker in lowered for marker in _SUDO_NEEDS_PASSWORD):
+        return _SUDO_HINT
+    return None
+
+
 @api_v3.route('/system/action', methods=['POST'])
 def execute_system_action():
     """Execute system actions (start/stop/reboot/etc)"""
@@ -206,7 +233,14 @@ def execute_system_action():
                     logger.error("start_display (%s) stderr: %s", mode, result.stderr.strip())
                 resp = {
                     'status': 'success' if result.returncode == 0 else 'error',
-                    'message': 'Display started' if result.returncode == 0 else 'Failed to start display',
+                    # This branch returns before the shared nonzero-result
+                    # response below, so it needs the hint of its own or an
+                    # on-demand start reports "Failed to start display" and
+                    # says nothing about the sudo that actually refused it.
+                    'message': (
+                        'Display started' if result.returncode == 0
+                        else _sudo_hint_for(result.stderr) or 'Failed to start display'
+                    ),
                 }
                 if result.returncode != 0:
                     resp['returncode'] = result.returncode
@@ -538,6 +572,9 @@ def execute_system_action():
         if result.returncode != 0:
             resp['returncode'] = result.returncode
             resp['stderr'] = result.stderr.strip()
+            hint = _sudo_hint_for(result.stderr)
+            if hint:
+                resp['message'] = hint
         return jsonify(resp)
 
     except subprocess.TimeoutExpired as e:
@@ -545,7 +582,13 @@ def execute_system_action():
         return jsonify({'status': 'error', 'message': 'Command timed out', 'returncode': -1, 'stderr': 'timeout'})
     except Exception as e:
         logger.error("execute_system_action failed: %s", e, exc_info=True)
-        return jsonify({'status': 'error', 'message': 'Action failed; see logs for details'}), 500
+        detail = describe_exception(e)
+        resp = {
+            'status': 'error',
+            'message': _sudo_hint_for(detail) or 'Action failed; see logs for details',
+            'details': detail,
+        }
+        return jsonify(resp), 500
 @api_v3.route('/system/git-info', methods=['GET'])
 def get_git_info():
     """Return branch, dirty state, recent commits and remote URL for the Tools tab."""