Manage native background processes with durable logs and owned cleanup

Author: ShadowfetchStudio

CHANGELOG.md

@@ -16,6 +16,10 @@
   task overrides, and recorded selection/fallback notices. Model registration
   distinguishes identical names on different endpoints and preserves saved
   credential references and context limits during discovery.
+- Native background processes run development servers and watchers alongside
+  tasks, retain bounded live logs and durable history, honor project permissions,
+  and stop managed child processes when the application closes. Legacy history
+  is imported without signalling stored PIDs or replaying old commands.
 - Native window automation covers actual tool execution, approvals, reload,
   cancellation, goal progression/pause, accessibility, and subprocess cleanup.
 - Native AppImage and Debian build scripts preserve per-format executable

README.md

@@ -14,7 +14,8 @@ context, tools, permissions, checkpoints, plans, and verification.
 desktop window with the interface embedded in the executable. It needs no Python
 runtime or browser launcher. See the [native development guide](docs/NATIVE_DESKTOP.md)
 and the [goals](docs/NATIVE_GOALS.md) and [model routing](docs/NATIVE_ROUTING.md)
-workflows. Development AppImage and Debian
+workflows, plus [managed background processes](docs/NATIVE_BACKGROUND.md).
+Development AppImage and Debian
 packages include [dependency inventories and notices](licenses/native/README.md).
 Integrations and release checks are
 still in progress under the [migration gates](docs/NATIVE_MIGRATION.md);

docs/NATIVE_BACKGROUND.md

@@ -0,0 +1,60 @@
+# Background processes in the native desktop
+
+Open **Background processes** in the sidebar, or the **Background** drawer tab.
+Give the process a name, enter its command, and choose **Start process**. This is
+useful for a development server or watcher that should continue while you work
+on other tasks in the same project. Commands run in the selected project folder.
+
+The panel shows process status, PID, start time, exit code, and live output.
+**Stop** waits for cleanup and retains the cancelled result. Stopping an already
+finished entry preserves its original completed or failed status. Duplicate
+active names are rejected within the same project.
+
+## Output and history
+
+The runner drains stdout and stderr continuously, including output without a
+newline. It preserves UTF-8 characters split across reads and keeps the most
+recent 64 KB of combined output in memory and SQLite. When that limit is reached,
+the panel indicates that older output was omitted. This is a log tail, not a
+complete terminal recording or interactive shell; stdin is closed.
+
+The process list sends a 4 KB preview per entry so a large history does not
+repeatedly transfer all retained logs. **Read retained output** opens a snapshot
+of the stored tail and full command; **Refresh retained output** updates that
+snapshot. **Return to live output** returns to the automatically refreshed preview.
+
+The panel shows the latest 100 entries for the current project, plus every active
+process even if it started before that history window. Older entries remain in
+SQLite. History and the retained log survive application restarts. The native
+migration imports legacy `background.db` history once without changing the
+original database; legacy active entries become interrupted history.
+
+## Permissions and lifecycle
+
+Starting a process is an explicit user command, like the Terminal Run button.
+The project must be trusted, read-only mode denies execution, and configured
+command restrictions still apply. The manager permits up to four active
+processes per project and sixteen per application profile. Background commands
+deliberately run alongside coding tasks; their shell side effects are not file
+tool checkpoints and are not undone by task rewind.
+
+Processes continue between tasks and while you navigate to another project.
+Return to their original project to view or stop them. They do not inherit the
+foreground terminal timeout. On Stop or normal application shutdown, ShadowCode
+sends SIGTERM, allows up to two seconds for the parent process to exit, and then
+kills remaining members of the managed process group. Shutdown waits for output
+draining and persisted status. A subprocess that deliberately detaches into a
+different session is outside that process group; this runner is not an OS sandbox.
+
+After an abrupt crash or forced termination, previously active records are marked
+**INTERRUPTED**. ShadowCode does not restart commands automatically or signal a
+persisted PID, which could now belong to an unrelated process. An interrupted
+record does not prove that an independently detached process has exited.
+
+The desktop uses Rust IPC routes `GET/POST /api/background`,
+`GET /api/background/<id>`, and `POST /api/background/<id>/stop`. The full native
+CLI and agent-facing background tools remain part of the broader integration
+work; this feature supplies the manager and user-operated desktop controls.
+
+See [verification](NATIVE_VERIFICATION.md) and the remaining
+[release gates](NATIVE_MIGRATION.md).

docs/NATIVE_DESKTOP.md

@@ -96,6 +96,9 @@ not require that tool. No global PATH change is needed.
 - [Model routing](NATIVE_ROUTING.md) selects a registered model for Plan, Build,
   Review, and Test. Provider-scoped IDs keep identical model names on different
   servers distinct; conversations retain the actual selection and fallback notices.
+- [Background processes](NATIVE_BACKGROUND.md) run project servers and watchers
+  alongside coding tasks, with live bounded logs, retained history, stop controls,
+  and process-group cleanup during application shutdown.
 
 ## Checks
 
@@ -121,7 +124,8 @@ and `SHADOW_WEBKIT_DRIVER` select explicit executable paths. Logs, screenshots,
 and a machine-readable result are written to `artifacts/native/`. This test
 checks the real embedded window, Rust IPC, approval, file and terminal tools,
 reload, cancellation, compact layout, model routing/fallback notices, goals and
-their live transcript, pause, light/dark/compact/goals/routing accessibility,
+their live transcript, pause, managed background processes,
+light/dark/compact/goals/routing/background accessibility,
 and managed shutdown. It also verifies
 that the executable embeds the current compiled interface and does not load
 `libpython`.

docs/NATIVE_MIGRATION.md

@@ -77,6 +77,10 @@ Implemented foundation:
   editable Plan/Build/Review/Test selections, preserved custom credentials and
   context limits, queued configuration snapshots, explicit per-task overrides,
   persisted model/fallback notices, and goal verification routed to Test.
+- [Managed background processes](NATIVE_BACKGROUND.md) for project servers and
+  watchers, with permission checks, bounded live log tails, durable status and
+  audit events, project-scoped controls, bounded concurrency, legacy history
+  import, and cancellation/shutdown that waits for process-group cleanup.
 - A persisted native task loop, per-workspace FIFO follow-ups, four concurrent
   workspaces, scoped approvals, cancellation that waits for cleanup, restart
   recovery, and atomic completion/usage/event commits. Continuation and branching

docs/NATIVE_VERIFICATION.md

@@ -6,7 +6,7 @@ remain in [NATIVE_MIGRATION.md](NATIVE_MIGRATION.md).
 
 ## Automated checks
 
-`cargo fmt --all --check`, Clippy with warnings denied, and all **78 native
+`cargo fmt --all --check`, Clippy with warnings denied, and all **89 native
 integration tests** pass on the development machine. The suite covers:
 
 - Config validation, private secrets, untrusted project overlays, profile locks,
@@ -42,6 +42,13 @@ integration tests** pass on the development machine. The suite covers:
   planning permissions, and goal verification through the Test model. A provider
   failure is checked to never send the task to the default endpoint; invalid
   settings are checked before writing secrets.
+- Background permission checks, logs without newlines, split UTF-8 output,
+  output floods with a bounded live tail, graceful/forced cancellation, child
+  cleanup, concurrent stop calls, per-project/global limits, project isolation,
+  coexistence with agent tasks, and shutdown. Restart/import tests preserve the
+  original legacy database and verify that an unrelated process with a stored PID
+  is never signalled. Active processes remain visible past 100 newer history
+  entries; failed audit storage prevents spawning an unrecorded command.
 
 The host's distro `rustdoc` needs its LLVM library directory in the loader path
 for doc tests. The full suite was run with:
@@ -67,7 +74,7 @@ The first window run exposed a SQLite LIKE escape bug that appeared only after
 sessions existed. A regression now covers real session listing and literal
 search. Visual inspection also found a cancellation transcript race and an open
 sidebar obscuring a resized compact window; the window test checks both.
-Axe WCAG 2 A/AA and 2.1 AA checks pass in light, dark, compact, Goals, and Router workspace
+Axe WCAG 2 A/AA and 2.1 AA checks pass in light, dark, compact, Goals, Router, and Background workspace
 views. The compact check caught the Review button losing its accessible name
 when its text was hidden; the control now retains an explicit label.
 The native test also creates a goal through the drawer, completes all three
@@ -80,6 +87,10 @@ confirms the chosen model in actual requests and the conversation, reloads its
 notice without duplication, and checks a visible default-model fallback for a
 missing saved route. The Router screenshot is inspected alongside the existing
 workspace views.
+The window test starts a background process through the form, inspects live and
+retained output, performs a coding task while it runs, and stops it through the
+drawer. It then closes the application with another background process and
+terminal child running, checking that the app and both managed process groups exit.
 Fourteen interface unit tests cover ordered replay, pagination, stream finalization,
 listener cleanup, interruption, native tool cards, routing/fallback replay, and
 disambiguated model labels that omit URL credentials. The seven existing browser