docs: update AGENTS.md with iframe auth, pool recovery, and shared helpers

database_api/AGENTS.md

@@ -35,6 +35,13 @@ extra_notes = db.Column(db.String(256), nullable=True, default=None)
 extra_notes = db.Column(db.String(256), nullable=False)
 ```
 
+## Shared helpers
+- `is_machai_user.py`: determines if a `user_id` belongs to a MachAI iframe
+  user (non-UUID, not in `UserAccount`, not the admin username). Used by both
+  `frontend_multi_user` and `worker_plan_database` — keep this as the single
+  source of truth for MachAI user detection. Must be called inside a Flask app
+  context.
+
 ## Testing
 - No package-level tests currently. If you change models or schema helpers,
   add a unit test under `database_api/tests` that exercises model import and

frontend_multi_user/AGENTS.md

@@ -63,6 +63,15 @@ models. Keep interfaces stable across services.
 - Plan retry in the frontend (`/plan/retry`) archives old incremental billing
   entries (`usage_billing_progress` → `usage_billing_settled`) instead of
   deleting them, preserving the original key's credit history.
+- MachAI iframe embedding:
+  - `/run` is exempt from CSRF (nonce provides replay protection) and does not
+    require `@login_required`. Unauthenticated iframe users pass `user_id` via
+    the form; authenticated users get their ID from the session.
+  - `/viewplan` and `/progress` skip login for plans owned by MachAI users
+    (determined via `database_api.is_machai_user`). Regular users still require
+    authentication and ownership checks.
+  - URL parameters use `plan_id` (not `run_id`). Route handler local variables
+    use `plan` (not `task`) when referring to a `PlanItem` row.
 - Forbidden imports: `worker_plan_internal`, `worker_plan.app`,
   `frontend_single_user`, `open_dir_server`.
 

worker_plan_database/AGENTS.md

@@ -46,6 +46,16 @@ PlanExe pipeline, and updates task state/progress.
   - Persist `activity_overview.json` into `PlanItem.run_activity_overview_json`.
   - Build `run_zip_snapshot` without `track_activity.jsonl` and set
     `run_artifact_layout_version` for new runs.
+- MachAI user detection: use `database_api.is_machai_user.is_machai_user()`
+  (shared with `frontend_multi_user`). The local `_should_send_to_machai()`
+  delegates to it. Do not duplicate the detection logic.
+- Connection pool recovery: `PGRES_TUPLES_OK` errors corrupt psycopg2
+  connections at the protocol level. After such errors, call
+  `db.engine.dispose()` to destroy the pool before `db.session.remove()`.
+  Without this, corrupted connections re-enter the pool and hang
+  `pool_pre_ping` checks, deadlocking all Luigi worker threads.
+- Luigi logging: loggers are set to INFO (not DEBUG) to suppress per-second
+  "Asking scheduler for work" / "pruning task graph" noise.
 - Forbidden imports: `worker_plan.app`, `frontend_*`, `open_dir_server`.
 
 ## Testing