feat(runtime): bind process and job resources to authority

docs/runtime-decomposition/wave-3-checkpoint-a-tests.txt

@@ -0,0 +1,145 @@
+tests/test_resource_identity.py
+tests/test_owned_resource_identity.py
+tests/test_remote_resource_identity.py
+tests/test_request_authority.py
+tests/test_tool_approvals.py
+tests/test_tool_approval_single_action_scope.py
+tests/test_tool_approval_task_scope.py
+tests/test_workspace_confine.py
+tests/test_tool_path_confinement.py
+tests/test_path_confinement_boundary.py
+tests/test_filesystem_tool_argument_validation.py
+tests/test_code_nav_tools.py
+tests/test_apply_patch_transaction.py
+tests/test_execution_bridge.py
+tests/test_production_external_bridge.py
+tests/test_turn_contract.py
+tests/test_turn_contract_read_operations.py
+tests/test_turn_contract_integration.py
+tests/test_agent_turn_contract_boundaries.py
+tests/test_explicit_personal_turn_contract.py
+tests/test_nested_invocation_ownership.py
+tests/test_containment_contract.py
+tests/test_containment_enforcement.py
+tests/test_containment_process_tree.py
+tests/test_native_execution_containment.py
+tests/test_background_containment.py
+tests/test_process_ownership.py
+tests/test_bg_jobs_store.py
+tests/test_bg_job_tools.py
+tests/test_execution_filesystem_boundary.py
+tests/test_mcp_manager.py
+tests/test_mcp_reconnect_args.py
+tests/test_mcp_text_error_normalization.py
+tests/test_mcp_param_hint_hardening.py
+tests/test_mcp_tool_params_in_prompt.py
+tests/test_mcp_memory_owner_scope.py
+tests/test_mcp_cache_invalidation.py
+tests/test_multiple_mcp_servers_timeout.py
+tests/test_mcp_dependency_compatibility.py
+tests/test_builtin_mcp_bg_tasks.py
+tests/test_builtin_mcp_pythonpath.py
+tests/test_builtin_mcp_npx_cache.py
+tests/test_mcp_add_server_args_validation.py
+tests/test_manage_mcp_command_allowlist.py
+tests/test_document_tool_owner_scope.py
+tests/test_owned_document_query.py
+tests/test_document_session_owner_scope.py
+tests/test_active_document_mutation_guard.py
+tests/test_native_document_stream.py
+tests/test_document_followup_integrity.py
+tests/test_document_active_restore.py
+tests/test_attachment_refs.py
+tests/test_upload_handler_atomicity.py
+tests/test_upload_handler_cleanup.py
+tests/test_upload_handler_rename_owner.py
+tests/test_upload_routes_owner_scope.py
+tests/test_resolve_upload_path_nondict.py
+tests/test_personal_upload_isolation.py
+tests/test_personal_upload_privilege.py
+tests/test_extract_text_tool.py
+tests/test_media_ingress.py
+tests/test_session_tools_registry.py
+tests/test_session_owner_attribution.py
+tests/test_session_list_owner_scope.py
+tests/test_session_endpoint_owner_scope.py
+tests/test_session_search.py
+tests/test_session_search_batch_fetch.py
+tests/test_history_topics_owner_scope.py
+tests/test_history_order_by_timestamp_regression.py
+tests/test_history_db_fallback_hidden.py
+tests/test_memory_owner_isolation.py
+tests/test_memory_routes_session_owner.py
+tests/test_manage_memory_json_contract.py
+tests/test_manage_memory_list.py
+tests/test_memory_store_unreadable_no_wipe.py
+tests/test_manage_notes_search_contract.py
+tests/test_notes_fail_closed_auth.py
+tests/test_notes_checklist_state.py
+tests/test_vault_password_not_in_argv.py
+tests/test_vault_routes_shim.py
+tests/test_external_context_tool_gate.py
+tests/test_chat_route_tool_policy.py
+tests/test_product_turn_contract_route.py
+tests/test_native_tool_result_threading.py
+tests/test_host_shell_polling.py
+tests/test_integrations_url_join.py
+tests/test_integration_api_call_ssrf.py
+tests/test_integrations_api_call_truncation.py
+tests/test_process_resource_identity.py
+tests/test_background_resource_identity.py
+tests/test_runtime_resource_integration.py
+tests/test_process_lifecycle.py
+tests/test_browser_lifecycle.py
+tests/test_private_browser_tool.py
+tests/test_browser_transport_recovery.py
+tests/test_shell_routes.py
+tests/test_agent_tmux_retirement.py
+tests/test_cookbook_stop_without_procfs.py
+tests/test_cookbook_serve_lifecycle.py
+tests/test_task_scheduler_cancel.py
+tests/test_task_shell_tools.py
+tests/test_runtime_behavior_regressions.py
+tests/test_workspace_artifact_tool_floor.py
+tests/test_bg_monitor_stream.py
+tests/test_orphan_reaping.py
+tests/test_cookbook_agent_tool_ssh_validation.py
+tests/test_codex_cookbook_admin_gate.py
+tests/test_task_cookbook_admin_gate.py
+tests/test_builtin_actions_cookbook_serve_state.py
+tests/test_cookbook_local_serve_pid_winpid.py
+tests/test_scheduler_restart_doublefire.py
+tests/test_task_scheduler_session_delivery.py
+tests/test_cookbook_cache_scan_isolation.py
+tests/test_cookbook_cached_scan_refresh.py
+tests/test_cookbook_chat_deeplinks_static.py
+tests/test_cookbook_cpu_only_serve.py
+tests/test_cookbook_dead_download_status.py
+tests/test_cookbook_dependency_completion_regression.py
+tests/test_cookbook_deps_recipes.py
+tests/test_cookbook_diagnosis.py
+tests/test_cookbook_diagnosis_js.py
+tests/test_cookbook_docker_access.py
+tests/test_cookbook_download_toast_duration.py
+tests/test_cookbook_endpoint_registration.py
+tests/test_cookbook_error_feedback.py
+tests/test_cookbook_error_tail_lines.py
+tests/test_cookbook_finished_download_label.py
+tests/test_cookbook_gemma4_thinking_template.py
+tests/test_cookbook_helpers.py
+tests/test_cookbook_hf_token.py
+tests/test_cookbook_official_trending_filter.py
+tests/test_cookbook_package_detection.py
+tests/test_cookbook_port_parsing_js.py
+tests/test_cookbook_progress_signal_js.py
+tests/test_cookbook_remote_windows_diffusers.py
+tests/test_cookbook_same_host_server_profiles_js.py
+tests/test_cookbook_tool_dry_run.py
+tests/test_cookbook_windows_stop_tree_js.py
+tests/test_scheduler_prompt_cache_time.py
+tests/test_scheduler_scheduled_time_validation.py
+tests/test_task_scheduler_cache.py
+tests/test_task_scheduler_fixture_isolation.py
+tests/test_tool_task_cancelled_on_disconnect.py
+tests/test_background_tool_jobs.py
+tests/test_deep_research_browser_fallback.py

docs/runtime-decomposition/wave-3-checkpoint-a.md

@@ -0,0 +1,215 @@
+# Wave 3 Checkpoint A: process and job authority
+
+This checkpoint binds native process creation and background-job operations to
+server-owned resources. It consumes the reconciled Wave 5B `ProcessIdentity`
+and leaves lifecycle and signalling mechanics unchanged. Browser document
+authority remains deferred; no browser session/page adapter is added here.
+
+## Baseline and boundaries
+
+Starting branch: `feature/runtime-resource-authority`.
+
+- HEAD: `d0d1b3697ccd567dad9f812ed9f4f4d4f7d0044f`.
+- Tree: `9a8a7fd490d18ab5ad9d627b41ddad81206017f2`.
+- Clean worktree, with `4052eecc`, `8ae6ee43` and `c3ad4d0b` as ancestors.
+- Unchanged Wave 3 + Wave 5B baseline: 2902 passed, 2 skipped, 2 existing
+  xfails across 100 files, using functional bubblewrap.
+
+The new identities add no operations to RequestAuthority or TurnContract.
+Transcription, OCR and tasks restrictions remain in force. There is no default
+DATA_DIR creation floor, PID grant, job wildcard or automatic descendant grant.
+Wave 4 effects, evidence, provenance and egress policy remain outside this
+checkpoint. Existing runtime outcome fields continue to report actual execution
+and teardown if identity attachment fails after execution.
+
+## Typed contracts
+
+`src/agent_runtime/resources.py` defines three immutable contracts:
+
+| Type | Binding | Source and validation |
+| --- | --- | --- |
+| `ProcessResource` | Producer namespace, application owner, originating request/thread, one nested Wave 5B `ProcessIdentity`, role, optional job and receipt linkage | Producer observation at spawn, or an already frozen containment lifecycle record. `owned()` and `exited()` validate the OS incarnation; they never establish application ownership. |
+| `ProcessLaunchResource` | Native producer, owner/request/thread, server UUID generation, exact normalized tool/input digest, native backend, sealed creation boundary, inherited authority digest | Reservation created during server normalization before spawn. Publication is exclusive for that generation. No PID is predicted or recovered from model text. |
+| `BackgroundJobResource` | Exact native store namespace, job ID, launch generation, owner/origin request/thread, containment ID, role-labelled process resources | The native producer registers the frozen supervisor observation before releasing the workload. Store, launch publication, authority sidecar and receipt must agree. |
+
+The admitted process producers are `native:containment` (leader and namespace
+init) and `native:bg_jobs` (supervisor). Manager/PTY/service observations are not
+silently enrolled; they require their own producer adapter. Leader, supervisor,
+namespace init and server manager remain distinct in Wave 5B records. Legacy
+flat PID/token fields remain for existing mechanics and are checked against the
+nested identity; the new envelope does not duplicate incarnation fields.
+
+`ProcessLaunchScope` binds a native Bash/Python backend, a sealed filesystem
+root, required containment dimensions, observed read-only runtime roots,
+network selector and maximum runtime. The producer compares its actual spec to
+the reservation. Changed roots, broader mounts, longer runtimes and changed
+backends fail closed. Credentials and command/environment contents are not
+serialized into resource identities.
+
+## Normalization and admission
+
+`src/agent_runtime/process_resources.py` centralizes scope sealing, resolution,
+validation, publication and ContextVar binding.
+
+1. RequestAuthority grants the semantic operation and explicitly seals existing
+   workspace/backend scope. Without a sealed creation scope, Bash/Python cannot
+   fall back to the server's working directory.
+2. Launch normalization issues one exact reservation. Job normalization resolves
+   the selector only within the immutable set of already admitted jobs.
+3. The dispatcher validates the exact resources before the approval claim and
+   binds the normalized operation in a ContextVar.
+4. Native producers revalidate operation, application binding, roots and spec.
+   Native Bash/Python dispatch remains pinned to the native backend and passes
+   owner/session context explicitly.
+5. Foreground publication precedes containment execution. Resulting process
+   envelopes reference the frozen leader/namespace-init records, never a fresh
+   capture of their numeric PIDs.
+6. Detached launch holds the supervisor on stdin. It observes its incarnation,
+   persists job/store/launch/sidecar linkage, then releases the command. The
+   worker independently checks those records, the supervisor, receipt and spec.
+   Publication failure closes the held worker and uses existing Wave 5B cleanup.
+
+Publication uses the existing atomic file/fsync and store-transaction APIs.
+There is no new effect journal or distributed commit protocol. Partial metadata
+cannot admit a job or release its workload.
+
+RequestAuthority snapshot version 4 carries explicit process, job and launch
+scopes. Older snapshots restore empty scopes; missing identities are never
+reconstructed by observing today's processes or jobs.
+
+## Approvals and child ceilings
+
+Proposal capture includes the exact reservation or job resource, including its
+nested process, role, producer, ownership, generation and receipt. The approval
+digest covers those resources and the existing exact operation/backend binding.
+Execution validates before the one-use claim and at producer entry. Restoring an
+exact operation restores no general process, job or launch scope. Unsupported
+standalone PID controls have no adapter and cannot create an approval identity.
+
+Child process scopes intersect by full identity equality after validating both
+parent and child observations. Jobs intersect by full store/ID/generation/
+owner/thread/receipt/process equality. Creation scopes may narrow roots, mounts,
+runtime or network limits while retaining the backend and parent boundary
+requirements. Semantic operation grants are intersected independently. A stale
+parent fails before a newly observed child can renew it. Discovering descendants
+or siblings adds no authority.
+
+ContextVar binding restores state on success, ordinary exception, cancellation
+and nesting. Existing lifecycle tests exercise cancellation during spawn and
+repeated cleanup; the new integration test also checks native dispatch context
+restoration during cancellation.
+
+## Job history and continuations
+
+`peek()` and resolution do not refresh or reap jobs. Output refresh reconciles
+only the selected job, including its owned subprocess handle. Stop/output/ack
+require the caller's exact expected resource and revalidate linkage. Results
+can update only an explicit result-field whitelist, never identity, owner,
+generation, receipt, PID, command, path or authority fields.
+
+Completed generations remain readable if their lifecycle receipt has been
+pruned, provided their application publication and sidecar remain exact.
+Completed stop is a no-op and cannot signal a reused PID. Active jobs require
+the exact native receipt and live supervisor; an existing receipt with changed
+producer/owner/incarnation or external semantics is rejected even for history.
+
+The monitor checks sidecar, launch generation, job resource and session owner
+before invoking a continuation and acknowledging that same generation. Missing
+legacy sidecars do not acquire authority. Service-owned maintenance/reaping
+remains independent of model authority; lookup never invokes it for siblings.
+Research records in `background_tool_jobs.py` remain records, not OS processes.
+
+## Reachable production seams
+
+| Production call path | Enforcement or explicit boundary |
+| --- | --- |
+| `agent_loop` / native executor -> `tool_execution.execute_tool_block` -> `BashTool.execute` / `PythonTool.execute` -> `_run_owned_command` | Exact reservation, native backend pin, explicit owner/session context, sealed spec and pre-execution publication. |
+| `execute_tool_block` -> `#!bg` -> `bg_jobs.launch` -> `containment_worker.supervise` | Held release until durable linkage; independent worker validation. |
+| Dispatcher -> `ManageBgJobsTool.execute` -> `bg_jobs.get` / `kill` | Exact captured job set/selector, owner/thread binding and revalidation; no implicit list refresh. |
+| App startup -> `bg_monitor._loop` -> `_run_followup` / `mark_followed_up` | Exact generation and sidecar/owner/thread validation before continuation and ack. |
+| `TaskScheduler._execute_action` -> `action_run_local` / `action_run_script` / local `action_ssh_command` -> `_run_subprocess` | Existing scheduler authority must permit the exact operation; new runner consumes a sealed launch ceiling through containment. Missing workspace/legacy creation scope fails closed. |
+| Dispatcher -> Cookbook native tools -> `/api/model/download`, `/api/model/serve`, `/api/cookbook/state`, `/api/cookbook/kill-pid` | Internal native mutation is rejected: UI state/session/PID discovery is not an application process registry. |
+| Dispatcher -> `stop_served_model` / `cancel_download` -> `_cookbook_kill_session` | Local targets fail closed before OS discovery, signalling or state changes. |
+| Generic `app_api` -> loopback shell/model/Cookbook namespaces | Generic private/owned route admission rejects these process-control namespaces. |
+| Direct labelled or unlabelled loopback -> shell native controls / local Cookbook launch/control | Internal markers confer no admin floor. Anonymous/auth-disabled native control fails closed, including missing auth-manager configurations. Authenticated human-admin control remains a separate administrative boundary. |
+| App startup -> process reaper / `bg_jobs.refresh` / `disown_unverified` / containment reaping | Existing service maintenance and frozen Wave 5B signal mechanics remain unchanged. |
+
+No production caller of `services/shell/service.py` was found; it is unchanged
+and not claimed as covered. Browser lifecycle, research/private browsers and
+their producer contracts are unchanged and outside Checkpoint A.
+
+## Unsupported paths and deployment consequences
+
+- Local Cookbook agent launch/control has no trustworthy application registry;
+  it is disabled instead of enrolling tmux/PID/UI observations.
+- Legacy Cookbook scheduled auto-stop uses the rejected internal shell route
+  and cannot silently resume control of editable UI-backed sessions. Its
+  absence of a trustworthy producer registry is an explicit remaining gap;
+  native background-job and containment reapers continue to work.
+- Auth-disabled native shell/Cookbook UI controls are unavailable: an anonymous
+  human request cannot be distinguished securely from a workload's loopback
+  request. No Origin header, browser key or local address substitutes for
+  resource authority.
+- Legacy tasks without creation scope and jobs without exact generation/sidecar
+  linkage do not gain authority during restoration.
+- Raw scheduled SSH execution fails closed until an exact external backend
+  producer exists. Existing remote Cookbook routes/MCP/bridges remain external;
+  a local SSH client is never enrolled as its remote workload.
+- Standalone existing-process/PTY/manager control, new producer registration,
+  browser session/page/document authority and general outbound-effect policy
+  are not implemented by this slice.
+
+## Control state and adversarial verification
+
+`PROCESS_RESOURCES_DIR`, the active launch directory, job store/sidecars and
+containment records are protected by central filesystem resource resolution.
+Native writable launch boundaries containing control state or existing
+symlink/hardlink aliases are rejected. Tests cover direct access, symlinks and
+hardlinks to launch records, job stores, authority sidecars and receipt files.
+These are pathname/inode observations. They do not claim race freedom against
+concurrent link replacement after validation; Wave 3-S containment mechanics
+have not been redesigned.
+
+The three new test files are `test_process_resource_identity.py`,
+`test_background_resource_identity.py` and `test_runtime_resource_integration.py`.
+They cover PID reuse/unverifiable or malformed observations, role/receipt/owner/
+request/thread substitution, generation replacement, publication failure and
+held release, immutable result fields, historical reads, sidecar mismatch,
+side-effect-free lookup, exact approval first use/replay/restoration, child
+ceilings, context restoration, external refusal, native routing, scheduler and
+anonymous/internal loopback bypasses, and TurnContract exclusions.
+
+The integrated manifest `wave-3-checkpoint-a-tests.txt` contains 145 files,
+including every file in the previous exact 88-file Wave 3 gate. It adds relevant
+Wave 5B lifecycle, shell, scheduler, Cookbook, background, browser transport and
+research fallback regressions. Run in an environment with functional bubblewrap:
+
+```sh
+python3 -m pytest -q -rs $(cat docs/runtime-decomposition/wave-3-checkpoint-a-tests.txt)
+python3 -m compileall -q app.py core routes services src tests scripts
+git diff --check
+git grep -n -E '^(<<<<<<< |=======$|>>>>>>> )' || true
+git ls-files -u
+```
+
+The final pre-commit gate passed 387 focused tests and 3364 integrated tests,
+with 3 platform skips and 2 existing xfails. The focused gate spans 12 files;
+the integrated gate spans the 145-file manifest. Validation used
+`/tmp/odysseus-wave3-validation/bin/python` with functional bubblewrap.
+Compileall, diff whitespace, conflict-marker and unmerged-index gates passed.
+The post-commit integrated result is recorded in the final checkpoint report.
+Platform skips remain
+explicit: `/tmp` is not a symlink, RLIMIT_AS can be lowered on this host, and the
+Windows-specific Ollama startup guard is not applicable on Linux. No missing
+browser dependency is converted into a passing test.
+
+## Remaining review concerns
+
+No known P0 admission bypass remains in the supported process/job paths.
+P1 compatibility gaps are the deliberately unsupported local Cookbook registry
+and auth-disabled native administration, plus legacy/unscoped scheduled work.
+P2 concerns are linear workspace/control-file scans and retention of private
+launch publications beyond job/receipt retention; a future server-owned
+maintenance policy must preserve exact historical linkage. Existing filesystem
+observation races and outbound-effect boundaries remain explicit limitations.
+Browser authority still requires the independent producer-contract lane.