# Jobs Unification — making every task a background job

**Status: shipped, except push notifications.** Phases 1–3 (data model, executor, queue, REST API and
the master-detail `/jobs` screen) are done and live. Phase 4 is the only open item, and is the reason
this file still exists. Email sync is deliberately NOT part of this any more — it moved into the email
sidecar with its own scheduling, so it does not appear in the Jobs list.

**Goal:** every task run (script, pipeline, later agentic) becomes a persisted, background **job** —
created over REST, streamed live over WebSocket, resumable/attachable, visible on desktop *and* phone,
and ending in a push notification. Replaces today's ephemeral script-task WebSocket path.

**Context:** jobs belong to the owner. Not because the platform is single-user — it stopped being that
on 2026-08-07 — but because `tasks` is an `execution` capability: running a job means running a script
as the owner's OS user, so it can never be granted to a member. "Is anything running?" is therefore
still a global check, and the conclusion below is unchanged even though the premise was rewritten.
Favor power-user affordances over guardrails.

## Current state (baseline)

- **Pipeline tasks** already are jobs: `pipeline_jobs` (Postgres) + `pipeline-job-manager` (in-memory
  live registry, viewer attach/replay buffer, 3s progress flush, finalize, restart-reconciliation) +
  `/jobs` list (`JobsScreen`) + `/jobs/:id` detail (`JobDetail`, live-attach or persisted). WS at
  `/api/tasks/pipeline/ws`.
- **Script tasks** (convert-video, edit-audio, …) run via `task-executor.ts` over `/api/tasks/run/ws`
  — **ephemeral, zero persistence**, dies with the tab. Modal `TaskRunnerModal` (ScriptRunner branch).
- A **separate** file-backed queue engine exists at `src/servers/queue/` (lane-serial, retries,
  crash-resume) wired only to email sync. NOT reused here — one Postgres jobs model instead.

## Decisions (locked)

- **Concurrency:** idle → single `Run` → `/jobs/:id`. Something running → `Queue` + a **red `Run`**
  (force concurrent). Run → start now → `/jobs/:id`. Queue → append `pending` → `/jobs` list.
  Backend (global): FIFO `pending` queue; on any finalize with 0 running, promote the oldest pending.
  Force-Run bypasses the queue. Queue backlog survives restart (promoteNext on startup).
- **Modal → page:** replace `TaskRunnerModal` with a `/jobs/new` route. Right-click task action
  navigates there instead of mounting the modal. One code path, phone-friendly.
- **Deep-link:** query params, not hash — `/jobs/new?task=convert-video&root=home&path=<dir>&entry=<name>`.
- **Phone:** already has a file browser, so it can pick a target path and POST a job. No blocker.
- **`inline` tasks stay in the modal.** A top-level `inline: true` in `TASK.md` marks quick/interactive
  tasks that run in the modal (ephemeral) instead of as a job. Default = job. Currently flagged:
  `remove-jelly-meta`, `analyze-video`, `clean-playlist-files`. So the modal is **not** retired — it's
  the inline path; the shared input form serves both the modal and `/jobs/new`. The flag is plumbed
  through the parser + task list/detail endpoints (`task.inline`), so the FileBrowser menu can branch.

## Plan

### Phase 1 — Unified jobs backend
- **1a. Data model.** Add `mode` (`pipeline|script|agentic`, default `pipeline`) + `exit_code` (int)
  to the jobs table. Log at `DATA_PATH/jobs/<id>.log` (derived from id). *Table/symbol rename
  `pipeline_jobs`→`jobs` is deferred as a cosmetic cleanup — add columns first, keep it working.*
- **1b. Execution.** Generalize the job manager: `startJob` takes `mode` and dispatches — `pipeline`
  → existing `executePipeline`; `script` → new `executeScript` (ports task-executor's
  `materializeScript`/`buildInputEnv`/bwrap sandbox/`killTree`/keepalive, but emits job events +
  appends stdout/stderr to the log file, finalizes with `exit_code`). Reuses the manager's
  viewer/broadcast/replay machinery.
- **1c. Scheduler.** `runningCount()` + FIFO `pending` promotion on finalize; `promoteNext()` on
  startup so a queued backlog resumes.

### Phase 2 — REST job API (decouples creation from the socket; enables the phone)
- `POST /jobs {taskDirName, inputs, cwd, action}` → `{jobId}` (create + start/queue, background).
- `GET /jobs` (+`?live=1`), `GET /jobs/:id`, `GET /jobs/:id/log?offset=`, `POST /jobs/:id/stop`.
- Consolidate the two WebSockets into one `/api/tasks/jobs/ws` doing only attach/stop/list.

### Phase 3 — Frontend
- `/jobs/new` → `NewJobScreen`: reads query params, renders the input UI lifted from
  `TaskRunnerModal` (`TaskInputForm` + per-group config + folder probing). Run/Queue per the
  concurrency UX. `JobDetail` gains a script branch (terminal output: live attach, or from log when
  idle). Retire `TaskRunnerModal`/`TaskRunnerDialog`/`useTaskRunner`. Header running-jobs indicator.

### Phase 4 — Notifications (later)
- One `notifyJobDone(job)` hook at finalize → push to the phone app.

## Progress
- [x] 1a data model — `mode` + `exit_code` columns (schema + applied to DB)
- [x] 1b executeScript + manager dispatch — `execute-script.ts` (spawn/sandbox/killTree port, log file,
      abort poll, returns exitCode), `process-tree.ts` (shared killTree), `pipeline-job-manager` now
      dispatches by `mode` and finalizes script jobs by exit code. *Compiles; runtime-untested until
      a REST caller + restart exist.*
- [x] 1c scheduler / queue — `enqueueJob(action)` (start now / queue behind running), `promoteNext()`
      on finalize + startup, `getOldestPendingJob`, `markInterruptedJobs` now running-only (pending
      queue survives restart). `startJob` kept as a `enqueueJob(...,'start')` wrapper.
- [x] 2 REST job API — `POST /jobs` (create script|pipeline, action start/queue), `GET /jobs` (+`?live=1`,
      now returns mode/exitCode/isLive), `GET /jobs/:id`, `GET /jobs/:id/log?offset=`, `POST /jobs/:id/stop`.
      Router mounted at `/jobs` and `/pipeline-jobs`. *Needs a restart to deploy; then curl/phone-testable.*
      WS consolidation still pending (old `/api/tasks/run/ws` + `/api/tasks/pipeline/ws` still live).
- [x] 3 frontend — master-detail `/jobs`, modal-as-creator, split list, header badges. Done.
  - [x] 3a jobs UI — **master-detail** `JobsPage` (like `/chat`): `WorkspaceLayout` with a list panel
        (left, polls `GET /jobs`, highlights active) + a detail panel (right) that branches by `mode`
        — `ScriptJobDetail` terminal (polls log + status, Stop) or `PipelineJobDetail`. One page serves
        both `/jobs` and `/jobs/:id`; list click navigates. Replaced the old separate list/detail pages.
  - [x] `inline` flag plumbed (parser + list/detail endpoints); 3 quick tasks flagged.
  - [x] 3b/3c task→job via the modal (pragmatic reuse). The task modal is now the job creator: on Run,
        an **inline** task runs ephemerally in-modal; a **non-inline** task `POST /jobs` (start) →
        navigates to `/jobs/:id`. When a job is already running, a red "Run now" + a "Queue" button
        (queue → `/jobs`). Reuses the modal's per-group input UI in place — no separate `/jobs/new`
        page or FileBrowser change needed. *(A standalone deep-linkable `/jobs/new` is deferred; the
        phone creates jobs directly via `POST /jobs`.)*
  - [x] 3d header job indicators — `JobsIndicator` (two always-present badges next to RescanButton +
        UserMenu): **running** (→ running job's `/jobs/:id`) + **queued** (→ `/jobs`), polling
        `GET /jobs/counts` → `{ running, runningJobId, queued }` every 3s; dim at 0.
- [ ] 4 push notifications