From 1095795b1c403ce81256a140ddb6cf122d4ada29 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Thu, 23 Apr 2026 18:16:22 +0100
Subject: [PATCH] =?UTF-8?q?docs(fleet):=20document=20fleet=20task=20?=
 =?UTF-8?q?=E2=89=A0=20AgentSession=20separation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fleet tasks deliberately do not create AgentSession records.
AgentSession's work_log / artefacts / handoff / replay semantics are
designed for interactive, replayable, handoff-capable work — fleet
tasks are atomic assign→complete events with no in-between state
to replay. If a fleet-task handler needs session semantics, it
should start its own AgentSession via AgentSessionService when the
work begins.

Closes tasks.lthn.sh/view.php?id=94

Co-authored-by: Codex <noreply@openai.com>
Co-Authored-By: Virgil <virgil@lethean.io>
---
 docs/php-agent/RFC.md              | 4 ++++
 php/Actions/Fleet/AssignTask.php   | 7 +++++++
 php/Actions/Fleet/CompleteTask.php | 7 +++++++
 3 files changed, 18 insertions(+)

diff --git a/docs/php-agent/RFC.md b/docs/php-agent/RFC.md
index 47d57a6..4b9ffe1 100644
--- a/docs/php-agent/RFC.md
+++ b/docs/php-agent/RFC.md
@@ -273,6 +273,10 @@ WorkspaceState::set($planId, 'discovered_pattern', 'observer');
 $pattern = WorkspaceState::get($planId, 'discovered_pattern');
 ```
 
+### 7.x Fleet tasks vs sessions
+
+Fleet tasks (AssignTask / CompleteTask) are deliberately out-of-session. AgentSession's work_log, artefacts, handoff, and replay semantics are designed for interactive / MCP-driven flows, not for the atomic assign→complete shape of fleet distribution. If a fleet task's handler needs session-style replay, that handler should start its own AgentSession via AgentSessionService when it begins the work.
+
 ---
 
 ## 8. API Key Security
diff --git a/php/Actions/Fleet/AssignTask.php b/php/Actions/Fleet/AssignTask.php
index 6672018..e964ea0 100644
--- a/php/Actions/Fleet/AssignTask.php
+++ b/php/Actions/Fleet/AssignTask.php
@@ -8,6 +8,13 @@ use Core\Actions\Action;
 use Core\Mod\Agentic\Models\FleetNode;
 use Core\Mod\Agentic\Models\FleetTask;
 
+/**
+ * Fleet tasks intentionally do not create AgentSession records. AgentSession tracks interactive,
+ * replayable, handoff-capable work with a work_log and artefact history; fleet tasks are atomic
+ * assign→complete events with no in-between state to replay. If a fleet task's work requires
+ * session semantics, the agent executing the task should start an AgentSession itself via
+ * AgentSessionService.
+ */
 class AssignTask
 {
     use Action;
diff --git a/php/Actions/Fleet/CompleteTask.php b/php/Actions/Fleet/CompleteTask.php
index 065858c..2f67848 100644
--- a/php/Actions/Fleet/CompleteTask.php
+++ b/php/Actions/Fleet/CompleteTask.php
@@ -9,6 +9,13 @@ use Core\Mod\Agentic\Actions\Credits\AwardCredits;
 use Core\Mod\Agentic\Models\FleetNode;
 use Core\Mod\Agentic\Models\FleetTask;
 
+/**
+ * Fleet tasks intentionally do not create AgentSession records. AgentSession tracks interactive,
+ * replayable, handoff-capable work with a work_log and artefact history; fleet tasks are atomic
+ * assign→complete events with no in-between state to replay. If a fleet task's work requires
+ * session semantics, the agent executing the task should start an AgentSession itself via
+ * AgentSessionService.
+ */
 class CompleteTask
 {
     use Action;