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

src/agent_runtime/authority.py

@@ -13,6 +13,7 @@ from uuid import uuid4
 
 from src.agent_runtime.resources import (
     FilesystemRoot, ExternalResource, NativeBackendResource, OwnedScope,
+    ProcessLaunchScope, ProcessResource, BackgroundJobResource,
     backend_from_dict, intersect_roots, seal_owned_scopes,
 )
 from src.tool_policy import ToolPolicy, build_effective_tool_policy
@@ -120,6 +121,9 @@ class RequestAuthority:
     resource_roots: tuple[FilesystemRoot, ...] | None = None
     backend_resources: tuple[ExternalResource | NativeBackendResource, ...] | None = None
     owned_scopes: tuple[OwnedScope, ...] | None = None
+    launch_scopes: tuple[ProcessLaunchScope, ...] | None = None
+    process_resources: tuple[ProcessResource, ...] = ()
+    job_resources: tuple[BackgroundJobResource, ...] | None = None
 
     def __post_init__(self):
         if (not isinstance(self.request_id, str) or not self.request_id
@@ -156,11 +160,29 @@ class RequestAuthority:
                 or any(not isinstance(s, OwnedScope) or (s.owner, s.thread_id) != (self.owner, self.session_id)
                        for s in self.owned_scopes)):
             raise ValueError("Malformed backend or owned resource scope")
+        from src.agent_runtime.process_resources import seal_launch_scopes, seal_jobs
+        if self.launch_scopes is None:
+            object.__setattr__(self, "launch_scopes", seal_launch_scopes(self))
+        if self.job_resources is None:
+            object.__setattr__(self, "job_resources", seal_jobs(self))
+        for field, kind in (("launch_scopes", ProcessLaunchScope), ("process_resources", ProcessResource),
+                            ("job_resources", BackgroundJobResource)):
+            values = getattr(self, field)
+            if not isinstance(values, tuple) or any(not isinstance(r, kind) for r in values):
+                raise ValueError("Malformed process resource scope")
+        if any(r.owner != self.owner for r in (*self.process_resources, *self.job_resources)):
+            raise ValueError("Process resource owner changed")
+        if any(s.root.owner and s.root.owner != self.owner for s in self.launch_scopes):
+            raise ValueError("Launch resource owner changed")
+        if any(r.thread_id != self.session_id for r in self.job_resources):
+            raise ValueError("Job resource thread changed")
+        if any(r.thread_id != (self.session_id or "request:" + self.request_id) for r in self.process_resources):
+            raise ValueError("Process resource thread changed")
 
     @classmethod
     def empty(cls, *, owner=None, session_id=None, workspace=None):
         return cls(uuid4().hex, _owner(owner), str(session_id or ""), str(workspace or ""),
-                   resource_roots=(), backend_resources=(), owned_scopes=())
+                   resource_roots=(), backend_resources=(), owned_scopes=(), launch_scopes=(), job_resources=())
 
     def bound_to(self, *, owner=None, session_id=None, workspace=None):
         return (self.owner == _owner(owner) and self.session_id == str(session_id or "")
@@ -188,6 +210,7 @@ class RequestAuthority:
         roots = ()
         backends = ()
         owned = ()
+        launches = processes = jobs = ()
         if (self.owner, self.session_id, self.workspace) == (child.owner, child.session_id, child.workspace):
             theirs = {g.tool: g for g in child.grants}
             grants = [g.intersect(theirs[g.tool]) for g in self.grants if g.tool in theirs]
@@ -195,10 +218,15 @@ class RequestAuthority:
             backends = tuple(r for r in self.backend_resources if r in child.backend_resources)
             owned = tuple(s for left in self.owned_scopes for right in child.owned_scopes
                           if (s := left.intersect(right)) is not None)
+            from src.agent_runtime.process_resources import intersect_observed, intersect_launch_scopes, validate_job
+            launches = intersect_launch_scopes(self.launch_scopes, child.launch_scopes)
+            processes = intersect_observed(self.process_resources, child.process_resources, lambda r: r.validate())
+            jobs = intersect_observed(self.job_resources, child.job_resources, validate_job)
         return replace(self, grants=tuple(grants), denied=self.denied | child.denied,
                        block_all=self.block_all or child.block_all,
                        disable_mcp=self.disable_mcp or child.disable_mcp, inherited=True,
-                       resource_roots=roots, backend_resources=backends, owned_scopes=owned)
+                       resource_roots=roots, backend_resources=backends, owned_scopes=owned,
+                       launch_scopes=launches, process_resources=processes, job_resources=jobs)
 
     def continuation(self, *, owner=None, session_id=None):
         """A server continuation may rebind a session, never change owner/grants."""
@@ -206,10 +234,12 @@ class RequestAuthority:
             return RequestAuthority.empty(owner=owner, session_id=session_id)
         rebound = str(session_id or "")
         return replace(self, session_id=rebound, inherited=True,
-                       owned_scopes=tuple(replace(s, thread_id=rebound) for s in self.owned_scopes) if rebound else ())
+                       owned_scopes=tuple(replace(s, thread_id=rebound) for s in self.owned_scopes) if rebound else (),
+                       process_resources=tuple(r for r in self.process_resources if r.thread_id == rebound),
+                       job_resources=tuple(r for r in self.job_resources if r.thread_id == rebound))
 
     def to_dict(self):
-        return {"version": 3, "request_id": self.request_id, "owner": self.owner,
+        return {"version": 4, "request_id": self.request_id, "owner": self.owner,
                 "session_id": self.session_id, "workspace": self.workspace,
                 "grants": [{"tool": g.tool,
                             "actions": None if g.actions is None else sorted(g.actions),
@@ -218,12 +248,15 @@ class RequestAuthority:
                 "disable_mcp": self.disable_mcp, "inherited": self.inherited,
                 "resource_roots": [r.to_dict() for r in self.resource_roots],
                 "backend_resources": [r.to_dict() for r in self.backend_resources],
-                "owned_scopes": [s.to_dict() for s in self.owned_scopes]}
+                "owned_scopes": [s.to_dict() for s in self.owned_scopes],
+                "launch_scopes": [s.to_dict() for s in self.launch_scopes],
+                "process_resources": [r.to_dict() for r in self.process_resources],
+                "job_resources": [r.to_dict() for r in self.job_resources]}
 
     @classmethod
     def from_dict(cls, value):
         if (not isinstance(value, dict) or type(value.get("version")) is not int
-                or value["version"] not in {1, 2, 3}):
+                or value["version"] not in {1, 2, 3, 4}):
             raise ValueError("Unsupported authority snapshot")
         def limits(value):
             if value is None:
@@ -234,8 +267,12 @@ class RequestAuthority:
         roots = value["resource_roots"] if value["version"] >= 2 else []
         if not isinstance(roots, list):
             raise ValueError("Malformed request resource snapshot")
-        backends = value["backend_resources"] if value["version"] == 3 else []
-        owned = value["owned_scopes"] if value["version"] == 3 else []
+        backends = value["backend_resources"] if value["version"] >= 3 else []
+        owned = value["owned_scopes"] if value["version"] >= 3 else []
+        process_fields = {name: value[name] if value["version"] >= 4 else []
+                          for name in ("launch_scopes", "process_resources", "job_resources")}
+        if any(not isinstance(v, list) for v in process_fields.values()):
+            raise ValueError("Malformed process resource snapshot")
         if not isinstance(backends, list) or not isinstance(owned, list):
             raise ValueError("Malformed request resource scope snapshot")
         return cls(value["request_id"], value["owner"], value["session_id"], value["workspace"],
@@ -243,7 +280,10 @@ class RequestAuthority:
                          for g in value["grants"]), limits(value["denied"]),
                    value["block_all"], value["disable_mcp"], value["inherited"],
                    tuple(FilesystemRoot.from_dict(r) for r in roots),
-                   tuple(backend_from_dict(r) for r in backends), tuple(OwnedScope.from_dict(s) for s in owned))
+                   tuple(backend_from_dict(r) for r in backends), tuple(OwnedScope.from_dict(s) for s in owned),
+                   tuple(ProcessLaunchScope.from_dict(s) for s in process_fields["launch_scopes"]),
+                   tuple(ProcessResource.from_dict(r) for r in process_fields["process_resources"]),
+                   tuple(BackgroundJobResource.from_dict(r) for r in process_fields["job_resources"]))
 
 
 _BROWSER_READ_ACTIONS = frozenset({"open", "navigate", "snapshot", "text", "read", "find",
@@ -462,7 +502,10 @@ def seal_task_authority(prompt, task_type, action, *, owner=None, parent_authori
                                             workspace=parent.workspace,
                                             resource_roots=parent.resource_roots,
                                             backend_resources=parent.backend_resources,
-                                            owned_scopes=parent.owned_scopes))
+                                            owned_scopes=parent.owned_scopes,
+                                            launch_scopes=parent.launch_scopes,
+                                            process_resources=parent.process_resources,
+                                            job_resources=parent.job_resources))
     return _json({"task_input": [prompt, task_type, action], "authority": authority.to_dict()})
 
 
@@ -479,18 +522,27 @@ def restore_task_authority(snapshot, prompt, task_type, action, *, owner=None, s
 def _background_path(job_id):
     if not isinstance(job_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]+", job_id):
         raise ValueError("Invalid background authority identity")
-    from src.constants import BG_JOBS_DIR
-    return Path(BG_JOBS_DIR) / (job_id + ".authority.json")
+    from src.bg_jobs import _JOBS_DIR
+    return Path(_JOBS_DIR) / (job_id + ".authority.json")
 
 
-def save_background_authority(job_id, authority):
+def save_background_authority(job_id, authority, *, resource=None):
     from core.atomic_io import atomic_write_json
-    atomic_write_json(_background_path(job_id), authority.to_dict())
+    if resource is None or resource.job_id != job_id:
+        raise ValueError("Background authority requires exact job linkage")
+    atomic_write_json(_background_path(job_id), {"authority": authority.to_dict(), "job": resource.to_dict()})
 
 
 def restore_background_authority(job_id, *, owner=None, session_id=None):
     try:
-        authority = RequestAuthority.from_dict(json.loads(_background_path(job_id).read_text()))
+        value = json.loads(_background_path(job_id).read_text())
+        resource = BackgroundJobResource.from_dict(value["job"])
+        from src.agent_runtime.process_resources import validate_job
+        validate_job(resource)
+        authority = RequestAuthority.from_dict(value["authority"])
+        if (resource.job_id, resource.owner, resource.thread_id, resource.request_id) != (
+                job_id, authority.owner, authority.session_id, authority.request_id):
+            raise ValueError("Background authority linkage changed")
         if authority.session_id != str(session_id or ""):
             raise ValueError("Background session changed")
         return authority.continuation(owner=owner, session_id=session_id)

src/agent_runtime/owned_resources.py

@@ -257,7 +257,8 @@ def needs_owned_binding(operation):
             raise ResourceIdentityError("Unresolved internal resource selector")
         path = posixpath.normpath(urlsplit(path).path)
         private = {"document", "documents", "session", "sessions", "history", "chat", "chats",
-                   "notes", "memory", "vault", "upload", "uploads", "attachments"}
+                   "notes", "memory", "vault", "upload", "uploads", "attachments",
+                   "shell", "model", "cookbook"}
         segments = path.strip("/").split("/")
         if len(segments) >= 2 and segments[0] == "api" and segments[1].casefold() in private:
             raise ResourceIdentityError("Owned records require a dedicated resource-bound tool")

src/agent_runtime/process_resources.py

@@ -0,0 +1,418 @@
+"""Process/job admission. Lifecycle mechanics remain in process_lifecycle.
+
+Only trusted launch producers publish observations. Persisted legacy records
+are never enrolled by looking at their PID. Receipts identify boundaries, not
+application authority. Resource snapshots contain no command or environment.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+from uuid import uuid4
+from core.atomic_io import store_transaction
+
+from src.agent_runtime.resources import (
+    BackgroundJobResource, NativeBackendResource, ProcessLaunchResource,
+    ProcessLaunchScope, ProcessResource, ResourceIdentityError,
+)
+from src.constants import PROCESS_RESOURCES_DIR
+
+_LAUNCH_DIR = Path(PROCESS_RESOURCES_DIR)
+LAUNCH_TOOLS = frozenset({"bash", "python"})
+JOB_TOOL = "manage_bg_jobs"
+_ACTIVE = ContextVar("process_resource_operation", default=None)
+
+
+def digest(value):
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def _thread(authority):
+    return authority.session_id or "request:" + authority.request_id
+
+
+def launch_path(generation):
+    if not isinstance(generation, str) or not re.fullmatch(r"[a-f0-9]{32}", generation):
+        raise ResourceIdentityError("Malformed launch generation")
+    return _LAUNCH_DIR / (generation + ".json")
+
+
+def seal_launch_scopes(authority):
+    return tuple(seal_launch_scope(backend, root)
+                 for backend in authority.backend_resources
+                 if isinstance(backend, NativeBackendResource) and backend.tool_id in LAUNCH_TOOLS
+                 for root in authority.resource_roots)
+
+
+def seal_launch_scope(backend, root, *, env=None):
+    from src.agent_tools.subprocess_tools import _owned_spec
+    from src.tool_execution import _agent_subprocess_env
+    from src.agent_runtime.resources import PathObservation, FileObjectIdentity
+    env = _agent_subprocess_env() if env is None else env
+    extra = tuple(Path(p).resolve().as_posix() for p in str(env.get("ODYSSEUS_PYTHON_TOOL_SITE_PACKAGES", "")).split(os.pathsep)
+                  if p and os.path.isabs(p)) if backend.tool_id == "python" else ()
+    spec = _owned_spec(root.path, env, 3600, extra)
+    return ProcessLaunchScope(backend, root, spec.required,
+        tuple(PathObservation(str(Path(p).resolve()), FileObjectIdentity.observe(Path(p).resolve())) for p in spec.readonly_extra),
+        spec.network, spec.wall_clock_s)
+
+
+def validate_launch_spec(launch, spec):
+    scope = launch.scope
+    scope.validate()
+    if (spec.workspace != scope.root.path or spec.required != scope.required or spec.network != scope.network
+            or spec.wall_clock_s > scope.max_runtime_s or spec.writable_extra
+            or tuple(spec.readonly_extra) != tuple(r.path for r in scope.runtime_roots)):
+        raise ResourceIdentityError("Producer launch boundary exceeds the sealed reservation")
+
+
+def job_from_record(record):
+    if not isinstance(record, dict):
+        raise ResourceIdentityError("Missing authoritative job")
+    try:
+        resource = BackgroundJobResource.from_dict(record["resource_identity"])
+        if (resource.namespace != "native:bg_jobs"
+                or (record["id"], record["session_id"], record["containment_id"])
+                != (resource.job_id, resource.thread_id, resource.containment_id)):
+            raise ValueError("Job linkage changed")
+        supervisor = next(p for p in resource.processes if p.role == "supervisor")
+        if (record.get("pid"), record.get("start_token"), record.get("pgid")) != (
+                supervisor.identity.pid, supervisor.identity.start_token, supervisor.identity.pgid):
+            raise ValueError("Supervisor linkage changed")
+        launch = ProcessLaunchResource.from_dict(record["launch_resource"])
+        if (launch.generation, launch.owner, launch.request_id, launch.thread_id) != (
+                resource.generation, resource.owner, resource.request_id, resource.thread_id):
+            raise ValueError("Launch/job linkage changed")
+        return resource
+    except (ValueError, TypeError, KeyError, StopIteration, AttributeError) as error:
+        raise ResourceIdentityError("Malformed or unowned background job") from error
+
+
+def validate_job(resource, *, mutation=False):
+    try:
+        return _validate_job(resource, mutation=mutation)
+    except ResourceIdentityError:
+        raise
+    except (ValueError, TypeError, OSError, KeyError, AttributeError) as error:
+        raise ResourceIdentityError("Background job linkage is missing or malformed") from error
+
+
+def validate_job_receipt(resource, receipt):
+    from src import containment
+    supervisor = resource.processes[0]
+    if (not isinstance(receipt, dict) or receipt.get("id") != resource.containment_id
+            or receipt.get("launch_generation") != resource.generation
+            or receipt.get("owner") != "bg:" + resource.thread_id
+            or (receipt.get("supervisor_pid"), receipt.get("supervisor_token")) !=
+            (supervisor.identity.pid, supervisor.identity.start_token)
+            or receipt.get("mechanism") not in {m.name for m in containment.MECHANISMS}
+            or receipt.get("external") is True):
+        raise ResourceIdentityError("Containment receipt linkage changed")
+
+
+def _validate_job(resource, *, mutation=False):
+    from src import bg_jobs, containment
+    if not isinstance(resource, BackgroundJobResource):
+        raise ResourceIdentityError("Missing exact background job identity")
+    record = bg_jobs.peek(resource.job_id)
+    if job_from_record(record) != resource:
+        raise ResourceIdentityError("Background job resource changed")
+    if record.get("status") not in {"running", "done", "failed"}:
+        raise ResourceIdentityError("Unknown job lifecycle")
+    launch = ProcessLaunchResource.from_dict(record["launch_resource"])
+    persisted = json.loads(launch_path(resource.generation).read_text())
+    if (persisted.get("launch") != launch.to_dict()
+            or persisted.get("job") != resource.to_dict()
+            or persisted.get("containment_id") != resource.containment_id):
+        raise ResourceIdentityError("Job/launch publication changed")
+    sidecar = json.loads((bg_jobs._JOBS_DIR / (resource.job_id + ".authority.json")).read_text())
+    origin = persisted.get("authority", {})
+    if (sidecar.get("job") != resource.to_dict() or sidecar.get("authority") != origin
+            or (origin.get("owner"), origin.get("request_id"), origin.get("session_id")) !=
+            (resource.owner, resource.request_id, resource.thread_id)):
+        raise ResourceIdentityError("Background authority linkage changed")
+    receipt = containment._load_records().get(resource.containment_id)
+    # Lifecycle receipts have a shorter retention than job results. A finished
+    # exact generation needs only its durable application linkage for history;
+    # it never regains signalling authority when its receipt has been pruned.
+    historical = record.get("status") in {"done", "failed"}
+    if receipt is None and not historical:
+        raise ResourceIdentityError("Missing active containment receipt")
+    if receipt is not None:
+        validate_job_receipt(resource, receipt)
+    if record.get("status") == "running":
+        for process in resource.processes:
+            try:
+                process.validate()
+            except ResourceIdentityError:
+                # Publication can precede store reconciliation. That exact
+                # completed generation is readable, but never signallable.
+                if mutation or not Path(record["exit_path"]).is_file():
+                    raise
+                report = json.loads(Path(record["result_path"]).read_text())
+                if report.get("resource_identity") != resource.to_dict() or report.get("containment", {}).get("id") != resource.containment_id:
+                    raise ResourceIdentityError("Historical result linkage changed")
+    # A completed record is readable history, never a new process observation.
+    return record
+
+
+def seal_jobs(authority):
+    if not any(g.tool == JOB_TOOL for g in authority.grants) or not authority.session_id:
+        return ()
+    from src import bg_jobs
+    admitted = []
+    for record in bg_jobs._load().values():
+        try:
+            resource = job_from_record(record)
+            if (resource.owner, resource.thread_id) == (authority.owner, authority.session_id):
+                validate_job(resource)
+                admitted.append(resource)
+        except (ValueError, TypeError, OSError, RuntimeError):
+            continue
+    return tuple(admitted)
+
+
+def intersect_observed(parent, child, validate):
+    # Validate both sides before equality. Seeing a replacement cannot renew a
+    # stale parent observation, even when the child has just sealed it.
+    for resource in (*parent, *child):
+        validate(resource)
+    return tuple(resource for resource in parent if resource in child)
+
+
+def intersect_launch_scopes(parent, child):
+    from src.agent_runtime.resources import FilesystemResource
+    for scope in (*parent, *child):
+        scope.validate()
+    narrowed = []
+    for left in parent:
+        for right in child:
+            if (left.backend != right.backend or not left.required <= right.required
+                    or right.max_runtime_s > left.max_runtime_s
+                    or not set(right.runtime_roots) <= set(left.runtime_roots)
+                    or (left.network == "none" and right.network != "none")):
+                continue
+            if Path(right.root.path).is_relative_to(left.root.path):
+                observation = FilesystemResource.resolve(left.root, right.root.path)
+                if observation.identity == right.root.identity:
+                    narrowed.append(right)
+    return tuple(dict.fromkeys(narrowed))
+
+
+@dataclass(frozen=True)
+class BoundProcessOperation:
+    operation: object
+    request_id: str
+    owner: str
+    thread_id: str
+    launch: ProcessLaunchResource | None = None
+    jobs: tuple[BackgroundJobResource, ...] = ()
+    processes: tuple[ProcessResource, ...] = ()
+    exact_approval: object | None = None
+
+    def __post_init__(self):
+        from src.agent_runtime.authority import ExactOperation
+        if (not isinstance(self.operation, ExactOperation) or not isinstance(self.request_id, str) or not self.request_id
+                or not isinstance(self.owner, str) or not isinstance(self.thread_id, str) or not self.thread_id
+                or (self.launch is not None and not isinstance(self.launch, ProcessLaunchResource))
+                or not isinstance(self.jobs, tuple) or any(not isinstance(j, BackgroundJobResource) for j in self.jobs)
+                or not isinstance(self.processes, tuple) or any(not isinstance(p, ProcessResource) for p in self.processes)):
+            raise ValueError("Malformed process-bound operation")
+        if self.launch is not None and (
+                (self.launch.owner, self.launch.request_id, self.launch.thread_id, self.launch.tool, self.launch.input_digest)
+                != (self.owner, self.request_id, self.thread_id, self.operation.tool, digest(self.operation.input))):
+            raise ValueError("Launch operation/application binding changed")
+        if any((r.owner, r.thread_id) != (self.owner, self.thread_id) for r in (*self.jobs, *self.processes)):
+            raise ValueError("Observed resource application binding changed")
+
+    def validate(self):
+        if self.launch is not None:
+            self.launch.validate()
+            guard_launch_workspace(self.launch.scope.root)
+        for job in self.jobs:
+            validate_job(job, mutation=self.operation.action in {"kill", "stop", "cancel", "terminate", "ack"})
+        for process in self.processes:
+            process.validate()
+
+    def to_dict(self):
+        return {"tool": self.operation.transport_tool, "input_digest": digest(self.operation.input),
+                "request_id": self.request_id, "owner": self.owner, "thread_id": self.thread_id,
+                "launch": self.launch.to_dict() if self.launch else None,
+                "jobs": [r.to_dict() for r in self.jobs], "processes": [r.to_dict() for r in self.processes]}
+
+
+def needs_process_binding(operation, backend):
+    return isinstance(backend, NativeBackendResource) and operation.tool in LAUNCH_TOOLS | {JOB_TOOL}
+
+
+def resolve_process_operation(authority, operation, backend, *, approved=None, exact_admission=False):
+    if not needs_process_binding(operation, backend):
+        raise ResourceIdentityError("No native process adapter for this backend")
+    if approved is not None:
+        if (approved.operation != operation or (approved.request_id, approved.owner, approved.thread_id)
+                != (authority.request_id, authority.owner, _thread(authority))):
+            raise ResourceIdentityError("Approved process operation binding changed")
+        bound = approved
+    elif operation.tool in LAUNCH_TOOLS:
+        scopes = [s for s in authority.launch_scopes if s.backend == backend]
+        if len(scopes) != 1:
+            raise ResourceIdentityError("Process creation requires a sealed workspace and launch scope")
+        launch = ProcessLaunchResource("native:containment", authority.owner, authority.request_id,
+            _thread(authority), uuid4().hex, operation.tool, digest(operation.input), scopes[0],
+            digest(json.dumps(authority.to_dict(), sort_keys=True)))
+        bound = BoundProcessOperation(operation, authority.request_id, authority.owner, _thread(authority), launch)
+    else:
+        try:
+            args = json.loads(operation.input)
+            action = str(args.get("action", "list")).strip().lower()
+            job_id = args.get("job_id", args.get("id", ""))
+        except (ValueError, TypeError, AttributeError) as error:
+            raise ResourceIdentityError("Malformed job operation") from error
+        if action in {"list", "ls", "jobs"}:
+            jobs = authority.job_resources
+        elif action in {"output", "get", "read", "tail", "status", "show", "kill", "stop", "cancel", "terminate", "ack"}:
+            if not isinstance(job_id, str) or not job_id:
+                raise ResourceIdentityError("An exact job selector is required")
+            jobs = tuple(r for r in authority.job_resources if r.job_id == job_id)
+            if len(jobs) != 1:
+                raise ResourceIdentityError("Job is outside admitted resource scope")
+        else:
+            raise ResourceIdentityError("Unsupported job operation")
+        bound = BoundProcessOperation(operation, authority.request_id, authority.owner, _thread(authority), jobs=jobs)
+    if not (approved is not None and exact_admission and not authority.inherited):
+        if bound.launch is not None and bound.launch.scope not in authority.launch_scopes:
+            raise ResourceIdentityError("Launch exceeds inherited creation scope")
+        if any(j not in authority.job_resources for j in bound.jobs) or any(p not in authority.process_resources for p in bound.processes):
+            raise ResourceIdentityError("Process/job exceeds inherited resource scope")
+    if bound.launch is not None and bound.launch.scope.backend != backend:
+        raise ResourceIdentityError("Launch backend changed")
+    bound.validate()
+    return bound
+
+
+def active_process_operation():
+    return _ACTIVE.get()
+
+
+@contextmanager
+def bind_process_operation(operation):
+    if operation is not None and not isinstance(operation, BoundProcessOperation):
+        raise TypeError("Process operation must be server-owned")
+    if operation is not None:
+        operation.validate()
+    token = _ACTIVE.set(operation)
+    try:
+        yield operation
+    finally:
+        _ACTIVE.reset(token)
+
+
+def require_launch(tool, *, cwd, content=None):
+    bound = active_process_operation()
+    if bound is None or bound.launch is None or bound.operation.tool != tool:
+        raise ResourceIdentityError("Native process producer has no bound launch reservation")
+    require_process_admission(bound)
+    bound.validate()
+    if Path(cwd).resolve() != Path(bound.launch.scope.root.path):
+        raise ResourceIdentityError("Launch workspace changed")
+    if content is not None and content.strip() != bound.operation.input.strip():
+        raise ResourceIdentityError("Launch operation changed at producer entry")
+    return bound.launch
+
+
+def require_process_admission(bound):
+    from src.agent_runtime.authority import active_request_authority
+    authority = active_request_authority()
+    if authority is None or (authority.owner, authority.request_id, _thread(authority)) != (
+            bound.owner, bound.request_id, bound.thread_id):
+        raise ResourceIdentityError("Producer application authority changed")
+    if not authority.permits(bound.operation):
+        approval = bound.exact_approval
+        if (authority.inherited or approval is None or not approval._claimed
+                or approval.pending.process_operation is None
+                or approval.pending.process_operation.to_dict() != bound.to_dict()):
+            raise ResourceIdentityError("Producer operation has no request admission or exact claim")
+
+
+def guard_launch_workspace(root):
+    """Reject a boundary containing execution control state or its aliases.
+
+    These are pathname/inode observations, not an atomic kernel access policy.
+    They do not claim freedom from concurrent link replacement after checking.
+    """
+    from src import bg_jobs, containment, constants
+    from src.agent_runtime.resources import _control_plane_path
+    control = (Path(bg_jobs._STORE), Path(bg_jobs._JOBS_DIR), containment._store_path(), _LAUNCH_DIR,
+               Path(constants.APP_DB), Path(constants.AUTH_FILE), Path(constants.SETTINGS_FILE))
+    base = Path(root.path)
+    if any(Path(p).resolve().is_relative_to(base) for p in control):
+        raise ResourceIdentityError("Launch boundary contains server control state")
+    def unresolved(error):
+        raise ResourceIdentityError("Launch workspace cannot be inspected") from error
+    for directory, dirs, files in os.walk(base, followlinks=False, onerror=unresolved):
+        for name in (*dirs, *files):
+            path = Path(directory) / name
+            info = path.lstat()
+            if (path.is_symlink() or info.st_nlink > 1) and _control_plane_path(str(path.resolve())):
+                raise ResourceIdentityError("Launch boundary aliases server control state")
+
+
+@store_transaction(lambda: _LAUNCH_DIR / "publication")
+def publish_launch(launch, authority, containment_id, *, job=None, processes=()):
+    from core.atomic_io import atomic_write_json
+    launch.validate()
+    if authority is None or (authority.owner, authority.request_id) != (launch.owner, launch.request_id):
+        raise ResourceIdentityError("Launch authority linkage changed")
+    path = launch_path(launch.generation)
+    if path.exists():
+        raise ResourceIdentityError("Launch reservation has already been used")
+    atomic_write_json(path, {"launch": launch.to_dict(), "authority": authority.to_dict(),
+                          "containment_id": containment_id, "job": job.to_dict() if job else None,
+                          "processes": [p.to_dict() for p in processes]})
+
+
+@store_transaction(lambda: _LAUNCH_DIR / "publication")
+def attach_containment_processes(launch, containment_id):
+    """Attach producer-frozen lifecycle records; never capture a current PID."""
+    from src import containment
+    from src.process_lifecycle import ProcessIdentity
+    record = containment._load_records().get(containment_id, {})
+    path = launch_path(launch.generation)
+    published = json.loads(path.read_text())
+    if (published.get("launch") != launch.to_dict() or published.get("containment_id") != containment_id
+            or record.get("id") != containment_id or record.get("launch_generation") != launch.generation
+            or record.get("workspace") != launch.scope.root.path):
+        raise ResourceIdentityError("Launch/receipt changed during publication")
+    processes = []
+    for role, pid_key, token_key, group_key in (("leader", "pid", "start_token", "pgid"),
+            ("namespace_init", "namespace_pid", "namespace_start_token", None)):
+        if record.get(pid_key):
+            processes.append(ProcessResource("native:containment", launch.owner, launch.request_id,
+                launch.thread_id, ProcessIdentity(record[pid_key], record.get(token_key), record.get(group_key) if group_key else None),
+                role, "", containment_id))
+    from core.atomic_io import atomic_write_json
+    published["processes"] = [p.to_dict() for p in processes]
+    atomic_write_json(path, published)
+
+
+def expected_job(job_id, *, action):
+    bound = active_process_operation()
+    if bound is None or bound.operation.tool != JOB_TOOL:
+        raise ResourceIdentityError("Job producer has no bound operation")
+    require_process_admission(bound)
+    # The caller's actual action must agree with the normalized proposal.
+    args = json.loads(bound.operation.input)
+    proposed = str(args.get("action", "list")).strip().lower()
+    if action != proposed:
+        raise ResourceIdentityError("Job action changed at producer entry")
+    target = next((j for j in bound.jobs if j.job_id == job_id), None)
+    if target is None:
+        raise ResourceIdentityError("Job selector is outside the bound operation")
+    validate_job(target, mutation=action in {"kill", "stop", "cancel", "terminate", "ack"})
+    return target

src/agent_runtime/resources.py

@@ -37,7 +37,10 @@ def _control_plane_path(path):
         "SETTINGS_FILE", "SESSIONS_FILE", "USER_PREFS_FILE", "VAULT_FILE",
         "SCHEDULED_EMAILS_DB", "EMAIL_CACHE_DB", "MEMORY_FILE", "INTEGRATIONS_FILE",
     )}
-    job_dirs = {canonical_root(constants.BG_JOBS_DIR)}
+    job_dirs = {canonical_root(constants.BG_JOBS_DIR), canonical_root(constants.PROCESS_RESOURCES_DIR)}
+    processes = sys.modules.get("src.agent_runtime.process_resources")
+    if processes is not None:
+        job_dirs.add(canonical_root(processes._LAUNCH_DIR))
     # Producers may have configured paths different from the default constants.
     # Inspect already-loaded server metadata without initializing a store here.
     bg = sys.modules.get("src.bg_jobs")
@@ -275,25 +278,165 @@ def intersect_roots(parent, child):
 @dataclass(frozen=True)
 class ProcessResource:
     namespace: str
-    incarnation: str
     owner: str
-    pid: int
-    start_token: str
+    request_id: str
+    thread_id: str
+    identity: "ProcessIdentity"
+    role: str
     job_id: str = ""
     containment_id: str = ""
-    namespace_pid: int | None = None
-    namespace_start_token: str = ""
 
     def __post_init__(self):
-        for name in ("namespace", "incarnation", "owner", "start_token"):
+        from src.process_lifecycle import ProcessIdentity
+        for name in ("namespace", "request_id", "thread_id"):
             _text(getattr(self, name), name)
-        for name in ("job_id", "containment_id", "namespace_start_token"):
+        for name in ("owner", "job_id", "containment_id"):
             _text(getattr(self, name), name, optional=True)
-        if (type(self.pid) is not int or self.pid <= 0
-                or (self.namespace_pid is not None and
-                    (type(self.namespace_pid) is not int or self.namespace_pid <= 0))
-                or bool(self.namespace_pid) != bool(self.namespace_start_token)):
+        if (not isinstance(self.identity, ProcessIdentity)
+                or type(self.identity.pid) is not int or self.identity.pid <= 0
+                or (self.identity.pgid is not None and (type(self.identity.pgid) is not int or self.identity.pgid <= 0))
+                or self.role not in {"supervisor", "leader", "namespace_init", "manager", "pty", "service"}):
             raise ValueError("Malformed process resource identity")
+        supported_roles = {"native:containment": {"leader", "namespace_init"},
+                           "native:bg_jobs": {"supervisor"}}
+        if self.role not in supported_roles.get(self.namespace, set()):
+            raise ValueError("Unsupported process producer or role")
+        _text(self.identity.start_token, "process start token")
+
+    def validate(self):
+        if not self.identity.owned() or self.identity.exited():
+            raise ResourceIdentityError("Process resource is stale or unverifiable")
+
+    def to_dict(self):
+        return {"namespace": self.namespace, "owner": self.owner, "request_id": self.request_id,
+                "thread_id": self.thread_id, "identity": self.identity.to_record(), "role": self.role,
+                "job_id": self.job_id, "containment_id": self.containment_id}
+
+    @classmethod
+    def from_dict(cls, value):
+        from src.process_lifecycle import ProcessIdentity
+        if not isinstance(value, dict) or set(value) != {"namespace", "owner", "request_id", "thread_id", "identity", "role", "job_id", "containment_id"}:
+            raise ValueError("Malformed process resource snapshot")
+        identity = value["identity"]
+        if not isinstance(identity, dict) or set(identity) != {"pid", "start_token", "pgid"}:
+            raise ValueError("Malformed lifecycle identity snapshot")
+        return cls(**{**value, "identity": ProcessIdentity(**identity)})
+
+
+@dataclass(frozen=True)
+class ProcessLaunchScope:
+    backend: "NativeBackendResource"
+    root: FilesystemRoot
+    required: frozenset[str]
+    runtime_roots: tuple[PathObservation, ...] = ()
+    network: str = "inherit"
+    max_runtime_s: int = 3600
+
+    def __post_init__(self):
+        if (not isinstance(self.backend, NativeBackendResource) or not isinstance(self.root, FilesystemRoot)
+                or not isinstance(self.required, frozenset) or not self.required
+                or any(not isinstance(v, str) or not v for v in self.required)):
+            raise ValueError("Malformed process launch scope")
+        if self.backend.tool_id not in {"bash", "python"}:
+            raise ValueError("Unsupported native launch producer")
+        if (not isinstance(self.runtime_roots, tuple) or any(not isinstance(r, PathObservation) for r in self.runtime_roots)
+                or self.network not in {"inherit", "none"}
+                or type(self.max_runtime_s) is not int or self.max_runtime_s <= 0):
+            raise ValueError("Malformed launch boundary selectors")
+
+    def validate(self):
+        self.root.validate()
+        for runtime in self.runtime_roots:
+            if canonical_root(runtime.path) != runtime.path or FileObjectIdentity.observe(runtime.path) != runtime.identity:
+                raise ResourceIdentityError("Launch runtime root changed")
+
+    def to_dict(self):
+        return {"backend": self.backend.to_dict(), "root": self.root.to_dict(), "required": sorted(self.required),
+                "runtime_roots": [{"path": r.path, "identity": asdict(r.identity)} for r in self.runtime_roots],
+                "network": self.network, "max_runtime_s": self.max_runtime_s}
+
+    @classmethod
+    def from_dict(cls, value):
+        if not isinstance(value, dict) or set(value) != {"backend", "root", "required", "runtime_roots", "network", "max_runtime_s"} or not isinstance(value["required"], list) or not isinstance(value["runtime_roots"], list):
+            raise ValueError("Malformed launch scope snapshot")
+        return cls(backend_from_dict(value["backend"]), FilesystemRoot.from_dict(value["root"]), frozenset(value["required"]),
+                   tuple(PathObservation(r["path"], FileObjectIdentity(**r["identity"])) for r in value["runtime_roots"]),
+                   value["network"], value["max_runtime_s"])
+
+
+@dataclass(frozen=True)
+class ProcessLaunchResource:
+    namespace: str
+    owner: str
+    request_id: str
+    thread_id: str
+    generation: str
+    tool: str
+    input_digest: str
+    scope: ProcessLaunchScope
+    ceiling_digest: str
+
+    def __post_init__(self):
+        for name in ("namespace", "request_id", "thread_id", "generation", "tool", "input_digest", "ceiling_digest"):
+            _text(getattr(self, name), name)
+        _text(self.owner, "owner", optional=True)
+        if not isinstance(self.scope, ProcessLaunchScope) or self.tool != self.scope.backend.tool_id:
+            raise ValueError("Malformed launch resource")
+        import re
+        if (self.namespace != "native:containment" or not re.fullmatch(r"[a-f0-9]{32}", self.generation)
+                or any(not re.fullmatch(r"[a-f0-9]{64}", v) for v in (self.input_digest, self.ceiling_digest))):
+            raise ValueError("Malformed native launch producer or generation")
+
+    def validate(self):
+        self.scope.validate()
+
+    def to_dict(self):
+        return {**{k: getattr(self, k) for k in ("namespace", "owner", "request_id", "thread_id", "generation", "tool", "input_digest", "ceiling_digest")},
+                "scope": self.scope.to_dict()}
+
+    @classmethod
+    def from_dict(cls, value):
+        if not isinstance(value, dict) or set(value) != {"namespace", "owner", "request_id", "thread_id", "generation", "tool", "input_digest", "scope", "ceiling_digest"}:
+            raise ValueError("Malformed launch resource snapshot")
+        return cls(**{**value, "scope": ProcessLaunchScope.from_dict(value["scope"])})
+
+
+@dataclass(frozen=True)
+class BackgroundJobResource:
+    namespace: str
+    job_id: str
+    generation: str
+    owner: str
+    request_id: str
+    thread_id: str
+    containment_id: str
+    processes: tuple[ProcessResource, ...]
+
+    def __post_init__(self):
+        for name in ("namespace", "job_id", "generation", "request_id", "thread_id", "containment_id"):
+            _text(getattr(self, name), name)
+        _text(self.owner, "owner", optional=True)
+        import re
+        if (not re.fullmatch(r"[A-Za-z0-9_-]+", self.job_id)
+                or not re.fullmatch(r"[a-f0-9]{32}", self.generation)):
+            raise ValueError("Malformed job selector or launch generation")
+        if (not isinstance(self.processes, tuple) or not self.processes
+                or any(not isinstance(p, ProcessResource) or (p.owner, p.request_id, p.thread_id, p.job_id, p.containment_id)
+                       != (self.owner, self.request_id, self.thread_id, self.job_id, self.containment_id) for p in self.processes)
+                or len({p.role for p in self.processes}) != len(self.processes)):
+            raise ValueError("Malformed background job resource")
+        if self.namespace != "native:bg_jobs" or any(p.namespace != "native:bg_jobs" or p.role != "supervisor" for p in self.processes):
+            raise ValueError("Unsupported job producer or process role")
+
+    def to_dict(self):
+        return {**{k: getattr(self, k) for k in ("namespace", "job_id", "generation", "owner", "request_id", "thread_id", "containment_id")},
+                "processes": [p.to_dict() for p in self.processes]}
+
+    @classmethod
+    def from_dict(cls, value):
+        if not isinstance(value, dict) or set(value) != {"namespace", "job_id", "generation", "owner", "request_id", "thread_id", "containment_id", "processes"} or not isinstance(value["processes"], list):
+            raise ValueError("Malformed background resource snapshot")
+        return cls(**{**value, "processes": tuple(ProcessResource.from_dict(p) for p in value["processes"])})
 
 
 @dataclass(frozen=True)