fuli-context 0.7.5 → 0.7.7

package/graph-provider/fuli_graph/store_task_contexts.py

@@ -0,0 +1,217 @@
+"""Task lifecycle shared by independent host-hook and MCP processes.
+
+Session and token nodes are locked in the same order. End-of-task claims bind
+an immutable payload fingerprint before side effects; retries can safely resume.
+"""
+
+import json
+
+from fastapi import HTTPException
+from neo4j.exceptions import ConstraintError
+
+from .personal_project_access import authorize_personal_project
+from .project_agent_access import authorize_project_agent
+from .provider_values import now_utc, stable_uuid
+from .project_agent_memory_models import ProjectAgentMemoryWrite
+from .store_transactions import query_store_transaction
+
+
+class StoreTaskContexts:
+    async def begin_task_context(self, actor, request):
+        self._require_personal()
+        space = await self.authorize(actor, request.personal_space_id, 'maintainer')
+        if request.personal_project_id:
+            await authorize_personal_project(self, actor, space, request.personal_project_id)
+        if request.project_agent_id:
+            agent = await authorize_project_agent(
+                self, actor, space, request.personal_project_id,
+                request.project_agent_id, require_active=True,
+            )
+            allowed_clients = json.loads(agent['profile_json']).get('allowed_clients', [])
+            if request.source_application not in allowed_clients:
+                raise HTTPException(status_code=403, detail='Agent is not allowed in this client')
+        record = request.model_dump(mode='json')
+        record.update(checkpoint=None, created_at=now_utc().isoformat())
+        try:
+            rows, _, _ = await self.runtime.driver.execute_query(
+                '''
+                MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})
+                MERGE (session:FuliTaskContextSession {id: $session_id})
+                SET session.write_serial = coalesce(session.write_serial, 0) + 1
+                MERGE (space)-[:HAS_TASK_CONTEXT_SESSION]->(session)
+                WITH session
+                OPTIONAL MATCH (session)-[:HAS_CONTEXT]->(previous:FuliTaskContext)
+                WHERE previous.token = session.current_token
+                WITH session, previous
+                OPTIONAL MATCH (session)-[:HAS_CONTEXT]->(retry:FuliTaskContext)
+                WHERE retry.token = $token OR ($turn_id IS NOT NULL AND retry.turn_id = $turn_id)
+                WITH session, previous, retry
+                ORDER BY CASE WHEN retry.token = $token THEN 0 ELSE 1 END, retry.id
+                LIMIT 1
+                FOREACH (ignored IN CASE WHEN retry IS NULL THEN [1] ELSE [] END |
+                  CREATE (task:FuliTaskContext {id: $context_id, token: $token,
+                    turn_id: $turn_id, record_json: $record_json, completed: false,
+                    personal_space_id: $space_id, personal_project_id: $project_id,
+                    project_agent_id: $agent_id, created_at: $created_at})
+                  CREATE (session)-[:HAS_CONTEXT]->(task)
+                  SET session.current_token = $token
+                )
+                WITH session, previous, retry
+                MATCH (session)-[:HAS_CONTEXT]->(saved:FuliTaskContext)
+                WHERE saved.token = coalesce(retry.token, $token)
+                RETURN saved.record_json AS record_json,
+                       saved.token = session.current_token AS is_current,
+                       previous IS NOT NULL AND NOT coalesce(previous.completed, false)
+                           AND previous.token <> saved.token AS previous_checkpoint_missing
+                ''',
+                space_id=request.personal_space_id,
+                session_id=self._task_session_id(
+                    request.personal_space_id, request.source_application, request.session_id,
+                ),
+                context_id=stable_uuid(request.personal_space_id, request.token),
+                token=request.token, turn_id=request.turn_id,
+                project_id=request.personal_project_id, agent_id=request.project_agent_id,
+                created_at=now_utc(),
+                record_json=json.dumps(record, ensure_ascii=False),
+            )
+        except ConstraintError as error:
+            # Tokens are space-wide handles; never attach one to another session.
+            raise HTTPException(status_code=409,
+                detail='Task context token is already in use') from error
+        if not rows[0]['is_current']:
+            raise HTTPException(status_code=409, detail='Task turn has been superseded')
+        saved = json.loads(rows[0]['record_json'])
+        for field in ('personal_project_id', 'project_agent_id', 'source_application', 'turn_id'):
+            if saved[field] != getattr(request, field):
+                raise HTTPException(status_code=409, detail='Task turn already has another context')
+        return {**saved, 'previous_checkpoint_missing': rows[0]['previous_checkpoint_missing']}
+
+    async def get_task_context(self, actor, space_id, token, source_application):
+        self._require_personal()
+        await self.authorize(actor, space_id, 'reader')
+        rows, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+                  [:HAS_TASK_CONTEXT_SESSION]->(session:FuliTaskContextSession)-
+                  [:HAS_CONTEXT]->(task:FuliTaskContext {token: $token})
+            WHERE session.current_token = task.token
+            RETURN task.record_json AS record_json
+            ''', space_id=space_id, token=token, routing_='r',
+        )
+        if not rows:
+            raise HTTPException(status_code=404, detail='Task context is unknown or superseded')
+        record = json.loads(rows[0]['record_json'])
+        if record['source_application'] != source_application:
+            raise HTTPException(status_code=404, detail='Task context not found for this client')
+        return record
+
+    async def checkpoint_task_context(self, actor, token, request):
+        if request.agent_memory is None:
+            return await self._checkpoint_task_context(actor, token, request)
+        # A rejected preparation cannot commit memory. A later host turn may
+        # still supersede a successfully prepared context; complete is separate.
+        async with query_store_transaction(self) as scoped:
+            record = await scoped._checkpoint_task_context(actor, token, request)
+            if not record['project_agent_id'] or not record['personal_project_id']:
+                raise HTTPException(status_code=409, detail='Task has no durable Agent memory target')
+            memory = await scoped.write_project_agent_memory(actor, ProjectAgentMemoryWrite(
+                personal_space_id=request.personal_space_id,
+                personal_project_id=record['personal_project_id'],
+                agent_id=record['project_agent_id'],
+                expected_revision=request.agent_memory.expected_revision,
+                memory=request.agent_memory.memory,
+                idempotency_key=f'{token}:memory',
+                source_application=record['source_application'],
+                # The client lifecycle session remains stable when entry and
+                # checkpoint hooks use different short-lived MCP processes.
+                source_session_id=record['session_id'],
+            ))
+            return {**record, 'agent_memory': memory.model_dump(mode='json')}
+
+    async def _checkpoint_task_context(self, actor, token, request):
+        await self.authorize(actor, request.personal_space_id, 'maintainer')
+        record = await self.get_task_context(
+            actor, request.personal_space_id, token, request.source_application,
+        )
+        checkpoint = request.model_dump(mode='json', exclude={
+            'personal_space_id', 'source_application', 'agent_memory',
+        })
+        # Complete retries must preserve the original completion timestamp/result.
+        record['checkpoint'] = checkpoint
+        # Bind memory presence independently of the caller's fingerprint. Its
+        # content is already immutable under the memory checkpoint's payload hash.
+        # The existing checkpoint lets pre-upgrade claims retry without new writes.
+        memory_checkpoint_id = None
+        if record['project_agent_id'] and record['personal_project_id']:
+            memory_checkpoint_id = stable_uuid(self._agent_memory_id(
+                request.personal_space_id, record['personal_project_id'],
+                record['project_agent_id'],
+            ), f'{token}:memory')
+        rows, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+                  [:HAS_TASK_CONTEXT_SESSION]->(session:FuliTaskContextSession)-
+                  [:HAS_CONTEXT]->(task:FuliTaskContext {token: $token})
+            SET session.write_serial = coalesce(session.write_serial, 0) + 1
+            WITH session, task
+            WHERE session.current_token = task.token
+            SET task.write_serial = coalesce(task.write_serial, 0) + 1
+            WITH task
+            OPTIONAL MATCH (memory:FuliProjectAgentMemoryCheckpoint {id: $memory_checkpoint_id})
+            WITH task, task.fingerprint IS NULL AS first_claim,
+                 coalesce(task.agent_memory_claimed, memory IS NOT NULL) AS memory_claimed
+            WITH task, first_claim OR (
+              task.fingerprint = $fingerprint AND task.disposition = $disposition
+              AND task.reason = $reason
+              AND (NOT $is_prepare OR memory_claimed = $has_agent_memory)
+            ) AS matches,
+            CASE WHEN first_claim THEN $has_agent_memory ELSE memory_claimed END AS memory_claimed
+            FOREACH (ignored IN CASE WHEN matches AND NOT task.completed THEN [1] ELSE [] END |
+              SET task.fingerprint = $fingerprint, task.record_json = $record_json,
+                  task.agent_memory_claimed = memory_claimed,
+                  task.completed = $completed, task.disposition = $disposition, task.reason = $reason
+            )
+            RETURN matches, task.record_json AS record_json
+            ''', space_id=request.personal_space_id, token=token,
+            fingerprint=request.fingerprint, record_json=json.dumps(record, ensure_ascii=False),
+            disposition=request.disposition, reason=request.reason,
+            completed=request.phase == 'complete',
+            is_prepare=request.phase == 'prepare',
+            has_agent_memory=request.agent_memory is not None,
+            memory_checkpoint_id=memory_checkpoint_id,
+        )
+        if not rows or not rows[0]['matches']:
+            raise HTTPException(status_code=409, detail='Task checkpoint conflicts or was superseded')
+        return json.loads(rows[0]['record_json'])
+
+    async def verify_task_checkpoint(self, actor, space_id, session_id, source_application):
+        self._require_personal()
+        await self.authorize(actor, space_id, 'reader')
+        rows, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+                  [:HAS_TASK_CONTEXT_SESSION]->(session:FuliTaskContextSession {id: $session_id})-
+                  [:HAS_CONTEXT]->(task:FuliTaskContext)
+            WHERE task.token = session.current_token
+            RETURN task.record_json AS record_json, task.completed AS completed
+            ''', space_id=space_id,
+            session_id=self._task_session_id(space_id, source_application, session_id),
+            routing_='r',
+        )
+        if not rows:
+            return {'status': 'not_started', 'guidance': 'No Fuli context started; do not block.'}
+        record = json.loads(rows[0]['record_json'])
+        if rows[0]['completed']:
+            return {'status': 'checkpointed', 'disposition': record['checkpoint']['disposition']}
+        return {
+            'status': 'checkpoint_required', 'decision': 'block',
+            'task_context_token': record['token'],
+            'reason': f'FULI_CHECKPOINT_REQUIRED: {record["token"]} '
+                'Before finishing, call checkpoint_task_knowledge using this task_context_token '
+                'with capture_candidates or retain_nothing; include agentMemory when durable '
+                'role context changed. Never store raw transcripts or credentials.',
+        }
+
+    def _task_session_id(self, space_id, source_application, session_id):
+        return stable_uuid(self.settings.provider_id, space_id, source_application,
+            session_id, 'task-context-session')

package/graph-provider/fuli_graph/store_transactions.py

@@ -0,0 +1,40 @@
+"""Explicit transaction scope for query-only Store operations.
+
+The scoped Store owns a private driver port. Never replace the shared runtime's
+driver: simultaneous HTTP requests must not borrow one another's transactions.
+"""
+
+from contextlib import asynccontextmanager
+from copy import copy
+from types import SimpleNamespace
+
+
+@asynccontextmanager
+async def query_store_transaction(store):
+    async with store.runtime.driver.transaction() as transaction:
+        scoped = copy(store)
+        # Query-only workflows intentionally have no raw Graphiti escape hatch.
+        scoped.runtime = SimpleNamespace(driver=TransactionQueryDriver(transaction))
+        yield scoped
+
+
+class TransactionQueryDriver:
+    """Adapt the Store execute_query port to one already-open transaction."""
+
+    def __init__(self, transaction):
+        self._transaction = transaction
+
+    async def execute_query(self, query, **kwargs):
+        parameters = dict(kwargs.pop('params', None) or {})
+        # The transaction already owns its session/routing. Reads must observe
+        # its uncommitted writes instead of opening an independent read session.
+        kwargs.pop('routing_', None)
+        parameters.update(kwargs)
+        result = await self._transaction.run(query, **parameters)
+        records = [record async for record in result]
+        return records, None, list(records[0].keys()) if records else []
+
+    @asynccontextmanager
+    async def transaction(self):
+        # Nested query-only operations join the owner; only it commits/rolls back.
+        yield self._transaction

package/graph-provider/fuli_graph/task_context_models.py

@@ -0,0 +1,50 @@
+"""Durable lifecycle metadata, never prompts, local paths or transcripts."""
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from .models import SourceApplication, StrictModel
+from .model_validation import reject_credentials
+from .project_agent_memory_models import ProjectAgentWorkingMemory
+
+
+class TaskContextBegin(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    personal_project_id: str | None = Field(default=None, min_length=1, max_length=128)
+    project_agent_id: str | None = Field(default=None, min_length=1, max_length=128)
+    session_id: str = Field(min_length=1, max_length=256)
+    source_application: SourceApplication
+    source_session_id: str | None = Field(default=None, min_length=1, max_length=256)
+    token: str = Field(pattern=r'^fuli-task-[a-zA-Z0-9-]{8,128}$')
+    turn_id: str | None = Field(default=None, min_length=1, max_length=256)
+    memory_revision: int | None = Field(default=None, ge=0)
+
+    @model_validator(mode='after')
+    def require_project_for_agent(self):
+        if self.project_agent_id and not self.personal_project_id:
+            raise ValueError('Agent lifecycle requires an exact project')
+        return self
+
+
+class TaskContextAgentMemory(StrictModel):
+    expected_revision: int = Field(ge=0)
+    memory: ProjectAgentWorkingMemory
+
+
+class TaskContextCheckpoint(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    source_application: SourceApplication
+    phase: Literal['prepare', 'complete'] = 'complete'
+    disposition: Literal['capture_candidates', 'retain_nothing']
+    reason: str = Field(min_length=1, max_length=2000)
+    fingerprint: str = Field(pattern=r'^[a-f0-9]{64}$')
+    capture_status: str | None = Field(default=None, max_length=128)
+    agent_memory: TaskContextAgentMemory | None = None
+
+    @model_validator(mode='after')
+    def reject_sensitive_values(self):
+        if self.agent_memory is not None and self.phase != 'prepare':
+            raise ValueError('Agent memory belongs to atomic checkpoint preparation')
+        reject_credentials(self, 'task checkpoint')
+        return self

package/graph-provider/fuli_graph/task_context_routes.py

@@ -0,0 +1,31 @@
+from typing import Annotated
+
+from fastapi import Query
+
+from .models import SourceApplication
+from .task_context_models import TaskContextBegin, TaskContextCheckpoint
+
+
+def register_task_context_routes(application, store, Actor):
+    @application.put('/v1/task-contexts')
+    async def begin_context(request: TaskContextBegin, actor: Actor):
+        return await store.begin_task_context(actor, request)
+
+    @application.get('/v1/task-contexts/{token}')
+    async def get_context(token: str, actor: Actor,
+        personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        source_application: SourceApplication):
+        return await store.get_task_context(actor, personal_space_id, token, source_application)
+
+    @application.put('/v1/task-contexts/{token}/checkpoint')
+    async def checkpoint_context(token: str, request: TaskContextCheckpoint, actor: Actor):
+        return await store.checkpoint_task_context(actor, token, request)
+
+    @application.get('/v1/task-context-sessions/checkpoint')
+    async def verify_checkpoint(actor: Actor,
+        personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        session_id: Annotated[str, Query(min_length=1, max_length=256)],
+        source_application: SourceApplication):
+        return await store.verify_task_checkpoint(
+            actor, personal_space_id, session_id, source_application,
+        )

package/graph-provider/fuli_graph/workflow_observation_models.py

@@ -24,7 +24,7 @@ class WorkflowTransitionObservation(StrictModel):
     observed_at: datetime
     evidence_summary: str = Field(min_length=1, max_length=2048)
     source_application: Literal[
-        'codex', 'claude_code', 'cursor', 'kiro', 'other'
+        'codex', 'claude', 'claude_code', 'cursor', 'kiro', 'other'
     ] | None = None
     source_turn_id: str | None = Field(default=None, min_length=1, max_length=256)
     sensitivity: Literal['normal', 'private', 'restricted'] = 'normal'

package/graph-provider/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.7.5"
+version = "0.7.7"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "fuli-context",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fuli-context",
-      "version": "0.7.5",
+      "version": "0.7.7",
       "license": "Apache-2.0",
       "dependencies": {
         "@hono/node-server": "2.0.12",
@@ -2950,9 +2950,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
-      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "version": "3.1.7",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.7.tgz",
+      "integrity": "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg==",
       "funding": [
         {
           "type": "github",
@@ -4397,9 +4397,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.15.3",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz",
-      "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==",
+      "version": "6.16.0",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz",
+      "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "es-define-property": "^1.0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fuli-context",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Local-first collaboration relationship graph for AI agents.",
   "type": "module",
   "files": [
@@ -10,6 +10,8 @@
     "dist/web/",
     "docs/external-knowledge-architecture.md",
     "docs/public-personal-architecture.md",
+    "docs/project-agent-memory.md",
+    "docs/employee-agents.md",
     "examples/external-knowledge/markdown-folder.mjs",
     "graph-provider/Dockerfile",
     "graph-provider/pyproject.toml",
@@ -99,6 +101,7 @@
       "@hono/node-server": "2.0.12"
     },
     "brace-expansion": "$brace-expansion",
-    "fast-uri": "3.1.5"
+    "fast-uri": "3.1.7",
+    "qs": "6.16.0"
   }
 }

package/skills/capturing-session-knowledge/SKILL.md

@@ -243,14 +243,26 @@ including concrete worker identity. Call `record_project_agent_executor_actual`
 executor/model use. If the host cannot start a worker, report the task as blocked or failed and do
 not fabricate an execution-summary row. The Provider's `executionSummary` remains authoritative.
 
+Keep per-worker completion separate from the global task transition. While parallel work is still
+being integrated, report each worker's terminal result in `workerStatus` and keep the task status
+`running`; this preserves one terminal execution-summary row per actual worker. Only after every
+required worker or participant result has been recorded should the coordinator send the final task
+`completed`, `failed`, or `cancelled` activity. Never let the first completed worker close the task
+before the remaining workers have reported their tools, session evidence, and exact Token usage.
+
 ## Report Actual Worker Execution
 
-When a FULI task or task view returns a non-empty Provider `executionSummary`, append one row per worker.
-Include the worker label and occupation emoji, actual executor and `sourceApplication` environment,
-work summary, and `workerStatus`/terminal status. This applies only to Provider-reported actual workers.
-When empty `executionSummary` is returned, omit rows; an absent `executionSummary` also omits rows.
-Configured, allowed, or available clients/executors are not evidence of actual use. Keep this
-Agent-agnostic; client-specific details and work-kind routing remain at adapter boundaries.
+When a FULI task or task view returns a non-empty Provider `executionSummary`, append a compact
+Markdown table with one row per actual worker. Include the worker label and occupation emoji,
+actual executor/tool plus `sourceApplication`, work summary, terminal `workerStatus`/status,
+session (`sourceSessionId`, or a session link only when the Provider supplies one), and Token usage.
+Use only the source-labelled cumulative `tokenUsage` reported for that worker. If it is absent,
+show `not reported`; never estimate it or copy a conversation-wide total into a worker row. If no
+session link exists, show `sourceSessionId` or `not reported`; never invent a link. This applies only
+to Provider-reported actual workers. When empty `executionSummary` is returned, omit rows; an absent
+`executionSummary` also omits rows. Configured, allowed, or available clients/executors are not evidence
+of actual use. Keep this Agent-agnostic; client-specific details and work-kind routing remain at
+adapter boundaries.
 
 ## Classify Knowledge State
 

package/src/adaptive-runtime/executor-pool.js

@@ -1,3 +1,5 @@
+const STOP_FAILURE_RETRY_MS = 30_000;
+
 export function createExecutorPool({
   adapters = new Map(),
   idleMs,
@@ -6,6 +8,7 @@ export function createExecutorPool({
 }) {
   const entries = new Map();
   let closed = false;
+  let closePromise = null;
 
   async function acquire(executorId, leaseId) {
     assertExecutorId(executorId);
@@ -21,20 +24,27 @@ export function createExecutorPool({
       return snapshotEntry(executorId, entry);
     }
     await exclusive(entry, async () => {
+      if (closed) throw new Error('Executor pool is closed');
       if (entry.stage !== 'running') {
-        entry.stage = 'starting';
         try {
+          if (entry.stage === 'failed' && !await stopEntry(executorId, entry)) {
+            throw new Error(entry.lastError);
+          }
+          entry.stage = 'starting';
           await entry.adapter.start({ executorId });
           entry.stage = 'running';
+          entry.lastStartError = null;
           entry.lastError = null;
         } catch (error) {
           entry.leases.delete(leaseId);
+          if (entry.stage === 'starting') entry.lastStartError = errorMessage(error);
           entry.stage = 'failed';
           entry.lastError = errorMessage(error);
           throw error;
         }
       }
     });
+    if (closed) throw new Error('Executor pool is closed');
     return snapshotEntry(executorId, entry);
   }
 
@@ -42,15 +52,27 @@ export function createExecutorPool({
     const entry = entries.get(executorId);
     if (!entry) return;
     entry.leases.delete(leaseId);
+    // Runtime entries are live lease bookkeeping, not durable Agent identities.
+    // External hosts have no resources owned by this pool after their last lease.
+    if (!entry.adapter && entry.leases.size === 0) {
+      entries.delete(executorId);
+      return;
+    }
+    scheduleStop(executorId, entry, idleMs);
+  }
+
+  function scheduleStop(executorId, entry, delay) {
     if (!entry.adapter || entry.leases.size > 0 || entry.timer || closed) return;
     entry.timer = setTimer(() => {
       entry.timer = null;
       if (entry.leases.size > 0 || closed) return;
       void exclusive(entry, async () => {
         if (entry.leases.size > 0 || closed) return;
-        await stopEntry(executorId, entry);
+        if (!await stopEntry(executorId, entry)) {
+          scheduleStop(executorId, entry, STOP_FAILURE_RETRY_MS);
+        }
       });
-    }, idleMs);
+    }, delay);
     entry.timer?.unref?.();
   }
 
@@ -59,10 +81,12 @@ export function createExecutorPool({
     try {
       await entry.adapter.stop({ executorId });
       entry.stage = 'idle';
-      entry.lastError = null;
+      entry.lastError = entry.lastStartError;
+      return true;
     } catch (error) {
       entry.stage = 'failed';
       entry.lastError = errorMessage(error);
+      return false;
     }
   }
 
@@ -72,11 +96,27 @@ export function createExecutorPool({
   }
 
   function close() {
+    if (closePromise) return closePromise;
     closed = true;
-    for (const entry of entries.values()) {
+    const shutdowns = [];
+    for (const [executorId, entry] of entries) {
       if (entry.timer) clearTimer(entry.timer);
       entry.timer = null;
+      entry.leases.clear();
+      if (entry.adapter) shutdowns.push(exclusive(entry, async () => {
+        if (entry.stage !== 'idle' && !await stopEntry(executorId, entry)) {
+          throw new Error(`Failed to stop managed executor ${executorId}: ${entry.lastError}`);
+        }
+      }));
     }
+    closePromise = Promise.allSettled(shutdowns).then((results) => {
+      const failures = results.filter((result) => result.status === 'rejected')
+        .map((result) => result.reason);
+      if (failures.length) {
+        throw new AggregateError(failures, failures.map((error) => error.message).join('; '));
+      }
+    });
+    return closePromise;
   }
 
   function entryFor(executorId) {
@@ -88,6 +128,7 @@ export function createExecutorPool({
         timer: null,
         transition: Promise.resolve(),
         stage: adapters.has(executorId) ? 'idle' : 'external',
+        lastStartError: null,
         lastError: null
       };
       entries.set(executorId, entry);

package/src/adaptive-runtime/graph-services.js

@@ -2,6 +2,7 @@ import { readJsonFile } from '../storage/json-file.js';
 import { createNativeGraphServices } from '../native-runtime/runtime.js';
 import {
   ensureContainerRuntime,
+  inspectContainerRuntime,
   runDockerCompose
 } from '../setup/container-runtime.js';
 import {
@@ -38,6 +39,7 @@ export function createManagedGraphServices({
   readJson = readJsonFile,
   readSettings = readRuntimeSettings,
   ensureRuntime = ensureContainerRuntime,
+  inspectRuntime = inspectContainerRuntime,
   runCompose = runDockerCompose,
   fetchImpl = globalThis.fetch,
   wait = delay,
@@ -80,15 +82,20 @@ export function createManagedGraphServices({
   }
 
   async function stopProviders() {
+    const selectedRuntime = inspectRuntime();
+    if (selectedRuntime.status === 'stopped') return;
     const services = managedServices();
-    compose(['stop', '-t', '20', ...services.providers], await runtime());
+    compose(['stop', '-t', '20', ...services.providers], selectedRuntime);
   }
 
   async function stopDatabases() {
+    // Inspect only: shutdown must not launch a desktop container engine to stop it.
+    const selectedRuntime = inspectRuntime();
+    if (selectedRuntime.status === 'stopped') return;
     const services = managedServices();
     // Keep shutdown ordering explicit even if an external action restarted a Provider.
-    compose(['stop', '-t', '20', ...services.providers], await runtime());
-    compose(['stop', '-t', '20', ...services.databases], await runtime());
+    compose(['stop', '-t', '20', ...services.providers], selectedRuntime);
+    compose(['stop', '-t', '20', ...services.databases], selectedRuntime);
   }
 
   async function ready() {