Borrowing: track detached session reattachment

Author: zhyongrui

docs/openclawcode/borrowing-delivery-plan.md

@@ -158,10 +158,18 @@ Completed in this wave:
 - `tasks show` / `flows show` now also expose `lookup` and `resolvedBy`, so
   detail views explain which operator token matched the underlying durable
   record
+- foreground `sessions continue` now stamps related task and TaskFlow records
+  with durable `reattachedAt` metadata, so detached work can later distinguish
+  "still backgrounded" from "brought back to the foreground"
+- that reattach metadata now shows up in `tasks show`, `flows show`, and
+  `sessions show` related-record payloads, giving operator views a first
+  durable hook for later completion-routing behavior
 
 Staged next:
 
 - non-CLI reattach affordances
+- completion routing and notifications that react differently once detached
+  work has been foreground-reattached
 - clearer remote-session lifecycle views in operator UIs
 
 ### 5. Bridge and remote-control subsystem boundaries

docs/reference/claudecode-borrowing.md

@@ -332,15 +332,22 @@ Implemented:
 - `openclaw tasks show` and `openclaw flows show` now also expose `lookup` and
   `resolvedBy`, so machine-readable detail views keep the same explicit
   resolution context as `sessions show`
+- foreground `openclaw sessions continue ...` now also stamps related detached
+  task and TaskFlow records with durable `reattachedAt` metadata, so later
+  operator views can tell whether the detached session stayed detached or was
+  explicitly brought back to the foreground
+- that `reattachedAt` state now surfaces in `tasks show`, `flows show`, and
+  `sessions show` related-record output, which establishes the substrate needed
+  for ClaudeCode-style completion routing that depends on reattach state
 
 Not implemented yet:
 
 - a richer "background my currently interactive TUI/Control-UI turn" affordance
   beyond the CLI entrypoint
 - session transcript handoff and recovery UX matching ClaudeCode's
   `LocalMainSessionTask` pattern
-- completion-routing behavior that depends on whether a detached task was
-  later reattached
+- the actual completion-routing behavior that depends on whether a detached
+  task was later reattached
 
 This keeps the first step deliberately narrow: make detached-session provenance
 durable and inspectable first, then build the foreground-to-background

src/commands/flows.show.detached-lifecycle.test.ts

@@ -155,6 +155,7 @@ describe("flowsShowCommand detached session lifecycle", () => {
     expect(output).toContain("resumeTranscript: n/a");
     expect(output).toContain("resumeTranscriptExists: no");
     expect(output).toContain("continueWith: openclaw sessions continue agent:coder:acp:child");
+    expect(output).toContain("reattachedAt: n/a");
 
     const jsonRun = makeRuntime();
     await flowsShowCommand({ lookup: flow.flowId, json: true }, jsonRun.runtime);
@@ -195,6 +196,26 @@ describe("flowsShowCommand detached session lifecycle", () => {
     });
   });
 
+  it("shows reattachedAt when the detached flow was later resumed in foreground", async () => {
+    const reattachedAt = Date.parse("2026-04-03T11:58:30Z");
+    const flow = createManagedTaskFlow({
+      ownerKey: "agent:coder:acp:owner-reattached",
+      controllerId: "tests/flows-show",
+      goal: "Continue detached work",
+      status: "waiting",
+      reattachedAt,
+    });
+
+    const textRun = makeRuntime();
+    await flowsShowCommand({ lookup: flow.flowId, json: false }, textRun.runtime);
+    expect(textRun.logs.join("\n")).toContain("reattachedAt: 2026-04-03T11:58:30.000Z");
+
+    const jsonRun = makeRuntime();
+    await flowsShowCommand({ lookup: flow.flowId, json: true }, jsonRun.runtime);
+    const payload = JSON.parse(jsonRun.logs[0] ?? "{}") as { reattachedAt?: number };
+    expect(payload.reattachedAt).toBe(reattachedAt);
+  });
+
   it("classifies an owner-key lookup in JSON output", async () => {
     const flow = createManagedTaskFlow({
       ownerKey: "agent:coder:acp:owner-lookup",

src/commands/flows.ts

@@ -326,6 +326,7 @@ export async function flowsShowCommand(
     ...(flow.cancelRequestedAt
       ? [`cancelRequestedAt: ${new Date(flow.cancelRequestedAt).toISOString()}`]
       : []),
+    `reattachedAt: ${flow.reattachedAt ? new Date(flow.reattachedAt).toISOString() : "n/a"}`,
     `createdAt: ${new Date(flow.createdAt).toISOString()}`,
     `updatedAt: ${new Date(flow.updatedAt).toISOString()}`,
     `endedAt: ${flow.endedAt ? new Date(flow.endedAt).toISOString() : "n/a"}`,

src/commands/sessions.continue.test.ts

@@ -1,5 +1,9 @@
 import fs from "node:fs";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { configureTaskFlowRegistryRuntime } from "../tasks/task-flow-registry.store.js";
+import { createManagedTaskFlow, getTaskFlowById, resetTaskFlowRegistryForTests } from "../tasks/task-flow-runtime-internal.js";
+import { configureTaskRegistryRuntime } from "../tasks/task-registry.store.js";
+import { createTaskRecord, getTaskById, resetTaskRegistryForTests } from "../tasks/runtime-internal.js";
 import { makeRuntime, mockSessionsConfig, writeStore } from "./sessions.test-helpers.js";
 
 const mocks = vi.hoisted(() => ({
@@ -15,9 +19,37 @@ mockSessionsConfig();
 import { sessionsContinueCommand } from "./sessions.js";
 
 describe("sessionsContinueCommand", () => {
+  const taskStore = {
+    loadSnapshot: () => ({
+      tasks: new Map(),
+      deliveryStates: new Map(),
+    }),
+    saveSnapshot: () => {},
+    upsertTaskWithDeliveryState: () => {},
+    upsertTask: () => {},
+    deleteTaskWithDeliveryState: () => {},
+    deleteTask: () => {},
+    upsertDeliveryState: () => {},
+    deleteDeliveryState: () => {},
+    close: () => {},
+  };
+  const flowStore = {
+    loadSnapshot: () => ({
+      flows: new Map(),
+    }),
+    saveSnapshot: () => {},
+    upsertFlow: () => {},
+    deleteFlow: () => {},
+    close: () => {},
+  };
+
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.agentCliCommandMock.mockResolvedValue({});
+    resetTaskRegistryForTests({ persist: false });
+    resetTaskFlowRegistryForTests({ persist: false });
+    configureTaskRegistryRuntime({ store: taskStore });
+    configureTaskFlowRegistryRuntime({ store: flowStore });
   });
 
   it("wraps JSON output with resolved session metadata and forwarded agent result", async () => {
@@ -303,4 +335,107 @@ describe("sessionsContinueCommand", () => {
       fs.rmSync(store, { force: true });
     }
   });
+
+  it("marks related tasks and flows as reattached for foreground continue", async () => {
+    const store = writeStore({
+      "agent:coder:acp:child": {
+        sessionId: "sess-child-continue-reattach",
+        updatedAt: Date.now() - 5 * 60_000,
+      },
+    });
+    const task = createTaskRecord({
+      runtime: "acp",
+      ownerKey: "agent:main:main",
+      scopeKind: "session",
+      childSessionKey: "agent:coder:acp:child",
+      originKind: "detached_session",
+      originSessionKey: "agent:main:main",
+      task: "Detached child",
+      status: "running",
+      deliveryStatus: "pending",
+      notifyPolicy: "state_changes",
+    });
+    const flow = createManagedTaskFlow({
+      ownerKey: "agent:coder:acp:child",
+      controllerId: "tests/sessions-continue",
+      goal: "Detached child",
+      status: "waiting",
+    });
+
+    try {
+      const { runtime, logs } = makeRuntime();
+      await sessionsContinueCommand(
+        {
+          lookup: "sess-child-continue-reattach",
+          message: "Bring this back to foreground",
+          store,
+          json: true,
+        },
+        runtime,
+      );
+
+      const updatedTask = getTaskById(task.taskId);
+      const updatedFlow = getTaskFlowById(flow.flowId);
+      expect(updatedTask?.reattachedAt).toBeTypeOf("number");
+      expect(updatedFlow?.reattachedAt).toBeTypeOf("number");
+
+      const payload = JSON.parse(logs[0] ?? "{}") as {
+        continuedSession?: { reattachedAt?: number | null };
+      };
+      expect(payload.continuedSession?.reattachedAt).toBe(updatedTask?.reattachedAt);
+      expect(updatedFlow?.reattachedAt).toBe(updatedTask?.reattachedAt);
+    } finally {
+      fs.rmSync(store, { force: true });
+    }
+  });
+
+  it("does not mark related tasks and flows as reattached for background continue", async () => {
+    const store = writeStore({
+      "agent:coder:acp:bg-child": {
+        sessionId: "sess-child-continue-bg",
+        updatedAt: Date.now() - 5 * 60_000,
+      },
+    });
+    const task = createTaskRecord({
+      runtime: "acp",
+      ownerKey: "agent:main:main",
+      scopeKind: "session",
+      childSessionKey: "agent:coder:acp:bg-child",
+      originKind: "detached_session",
+      originSessionKey: "agent:main:main",
+      task: "Detached child",
+      status: "running",
+      deliveryStatus: "pending",
+      notifyPolicy: "state_changes",
+    });
+    const flow = createManagedTaskFlow({
+      ownerKey: "agent:coder:acp:bg-child",
+      controllerId: "tests/sessions-continue",
+      goal: "Detached child",
+      status: "waiting",
+    });
+
+    try {
+      const { runtime, logs } = makeRuntime();
+      await sessionsContinueCommand(
+        {
+          lookup: "sess-child-continue-bg",
+          message: "Keep it detached",
+          store,
+          json: true,
+          background: true,
+        },
+        runtime,
+      );
+
+      expect(getTaskById(task.taskId)?.reattachedAt).toBeUndefined();
+      expect(getTaskFlowById(flow.flowId)?.reattachedAt).toBeUndefined();
+      const payload = JSON.parse(logs[0] ?? "{}") as {
+        continuedSession?: { reattachedAt?: number | null };
+      };
+      expect(payload.continuedSession?.reattachedAt).toBeNull();
+    } finally {
+      fs.rmSync(store, { force: true });
+    }
+  });
 });

src/commands/sessions.show.test.ts

@@ -181,12 +181,14 @@ describe("sessionsShowCommand", () => {
         {
           runId: "run-detached-1",
           originKind: "detached_session",
+          reattachedAt: null,
         },
       ],
       relatedTaskFlows: [
         {
           controllerId: "tests/sessions-show",
           status: "waiting",
+          reattachedAt: null,
         },
       ],
       resume: {
@@ -210,6 +212,61 @@ describe("sessionsShowCommand", () => {
     );
   });
 
+  it("shows reattached metadata on related tasks and flows", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-sessions-show-reattached-"));
+    tempDirs.push(root);
+    const store = path.join(root, "sessions.json");
+    fs.writeFileSync(
+      store,
+      JSON.stringify(
+        {
+          "agent:coder:acp:child-reattached": {
+            sessionId: "sess-child-reattached",
+            updatedAt: Date.now() - 5 * 60_000,
+          },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    const reattachedAt = Date.parse("2026-04-03T11:58:30Z");
+    createTaskRecord({
+      runtime: "acp",
+      ownerKey: "agent:main:main",
+      scopeKind: "session",
+      childSessionKey: "agent:coder:acp:child-reattached",
+      originKind: "detached_session",
+      originSessionKey: "agent:main:main",
+      task: "Continue detached work",
+      status: "running",
+      deliveryStatus: "pending",
+      notifyPolicy: "state_changes",
+      reattachedAt,
+    });
+    createManagedTaskFlow({
+      ownerKey: "agent:coder:acp:child-reattached",
+      controllerId: "tests/sessions-show",
+      goal: "Continue detached work",
+      status: "waiting",
+      reattachedAt,
+    });
+
+    const { runtime, logs } = makeRuntime();
+    await sessionsShowCommand(
+      {
+        lookup: "sess-child-reattached",
+        store,
+        json: false,
+      },
+      runtime,
+    );
+
+    const output = logs.join("\n");
+    expect(output).toContain("[reattached 2026-04-03T11:58:30.000Z]");
+  });
+
   it("classifies a session with a missing transcript as missing_transcript", async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-sessions-show-missing-"));
     tempDirs.push(root);