feat(workhub): persist delegation linkage

apps/desktop/src/main/__tests__/desktop-session-projection.test.ts

@@ -24,6 +24,7 @@ import type { SessionSummary } from '@maka/core/session';
 import {
   projectDesktopSessionEvent,
   projectDesktopSessionSummary,
+  projectDesktopStoredMessage,
   projectDesktopTurnRecord,
 } from '../../shared/desktop-session-projection.js';
 
@@ -145,6 +146,32 @@ test('projects queued Session attachments into the Desktop host namespace', () =
   );
 });
 
+test('projects durable WorkHub delegation targets into the Desktop host namespace', () => {
+  const projected = projectDesktopStoredMessage(
+    { hostId: 'remote-root' },
+    {
+      type: 'workhub_coordination',
+      id: 'delegation-commit-message',
+      turnId: 'coordination-turn',
+      ts: 2,
+      schemaVersion: 1,
+      kind: 'delegation_committed',
+      actionId: 'action-id',
+      actionFingerprint: `sha256:${'a'.repeat(64)}`,
+      coordinationTurnId: 'coordination-turn',
+      targetSessionId: 'payments',
+      disposition: 'delegate_existing',
+      delegationId: 'delegation-id',
+      targetTurnId: 'payments-turn',
+    },
+  );
+
+  assert.equal(projected.type, 'workhub_coordination');
+  if (projected.type === 'workhub_coordination') {
+    assert.equal(projected.targetSessionId, JSON.stringify(['remote-root', 'payments']));
+  }
+});
+
 function summary(id: string): SessionSummary {
   return {
     id,

apps/desktop/src/shared/desktop-session-projection.ts

@@ -124,6 +124,11 @@ export function projectDesktopStoredMessage(
       return message.parentSessionId
         ? { ...message, parentSessionId: projectSessionId(host, message.parentSessionId) }
         : message;
+    case 'workhub_coordination':
+      return {
+        ...message,
+        targetSessionId: projectSessionId(host, message.targetSessionId),
+      };
     default:
       return message;
   }

docs/architecture/workhub-coordination-session-adr.md

@@ -114,6 +114,15 @@ authoritative result. WorkHub may display a bounded projection or record a
 coordination summary, but it does not copy the ordinary Session's complete
 transcript into the Coordination Session.
 
+Delegation linkage uses closed, typed `workhub_coordination` records in the
+existing Coordination Session transcript. An immutable `delegation_intent` is
+appended before the target Session effect so an opaque candidate remains
+recoverable after the candidate set changes or the Runtime Host restarts. A
+`delegation_committed` record then binds that intent to the accepted target Turn
+and acts as the durable action-replay result. The records carry an action
+fingerprint to reject conflicting reuse of an action identity. They do not form a
+general workflow state machine and do not persist target execution lifecycle.
+
 ## Consequences, costs, and reevaluation
 
 - WorkHub gains persistent conversational continuity without adding another
@@ -129,9 +138,10 @@ transcript into the Coordination Session.
   entity remains unresolved.
 - Cross-Runtime-Host coordination remains deferred.
 - Coordination Session role representation, lazy creation, durable lookup,
-  recovery, and per-Host UI resolution are implemented. Coordination transcript,
-  disposition, delegation-link, and Action Gate behavior remain later work; this
-  ADR defines their authority boundaries without implementing them.
+  recovery, per-Host UI resolution, persistent transcript, closed dispositions,
+  and the Action Gate are implemented. Durable delegation linkage is encoded in
+  that transcript; target lifecycle projection and destructive replacement/Stop
+  recovery remain later work.
 
 Reevaluate the per-Host decision if supported workflows require one WorkHub
 conversation to coordinate ordinary Sessions on multiple Runtime Hosts, or if Host

packages/core/src/__tests__/workhub-coordination-record.test.ts

@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { decodeCanonicalMessage } from '../session.js';
+
+const FINGERPRINT = `sha256:${'a'.repeat(64)}`;
+
+describe('WorkHub Coordination stored records', () => {
+  test('decodes exact delegation intent and commit records', () => {
+    const intent = {
+      type: 'workhub_coordination',
+      id: 'intent-id',
+      turnId: 'coordination-turn',
+      ts: 1,
+      schemaVersion: 1,
+      kind: 'delegation_intent',
+      actionId: 'action-id',
+      actionFingerprint: FINGERPRINT,
+      coordinationTurnId: 'coordination-turn',
+      targetSessionId: 'payments',
+      disposition: 'delegate_existing',
+    } as const;
+    const committed = {
+      ...intent,
+      id: 'commit-id',
+      ts: 2,
+      kind: 'delegation_committed',
+      delegationId: 'delegation-id',
+      targetTurnId: 'target-turn',
+      steered: true,
+    } as const;
+
+    assert.deepEqual(decodeCanonicalMessage(intent), intent);
+    assert.deepEqual(decodeCanonicalMessage(committed), committed);
+  });
+
+  test('rejects malformed or widened coordination records', () => {
+    const base = {
+      type: 'workhub_coordination',
+      id: 'intent-id',
+      turnId: 'coordination-turn',
+      ts: 1,
+      schemaVersion: 1,
+      kind: 'delegation_intent',
+      actionId: 'action-id',
+      actionFingerprint: FINGERPRINT,
+      coordinationTurnId: 'coordination-turn',
+      targetSessionId: 'payments',
+      disposition: 'delegate_existing',
+    } as const;
+
+    for (const invalid of [
+      { ...base, coordinationTurnId: 'different-turn' },
+      { ...base, actionFingerprint: 'not-a-digest' },
+      { ...base, disposition: 'replace' },
+      { ...base, sourceSessionId: 'injected' },
+      { ...base, kind: 'delegation_committed' },
+      { ...base, schemaVersion: 2 },
+    ]) {
+      assert.throws(() => decodeCanonicalMessage(invalid), /Invalid stored message schema/u);
+    }
+  });
+});

packages/core/src/session.ts

@@ -756,6 +756,7 @@ export type StoredMessage =
   | PermissionDecisionMessage
   | TokenUsageMessage
   | TurnStateMessage
+  | WorkHubCoordinationMessage
   | SystemNoteMessage;
 
 export interface UserMessage extends MessageContent {
@@ -908,6 +909,41 @@ export interface TurnStateMessage {
   partialOutputRetained: boolean;
 }
 
+export const WORKHUB_COORDINATION_RECORD_SCHEMA_VERSION = 1 as const;
+
+export type WorkHubDelegationDisposition = 'delegate_existing' | 'create_new';
+
+interface WorkHubCoordinationMessageEnvelope {
+  type: 'workhub_coordination';
+  id: string;
+  /** The Coordination Turn that owns this action. */
+  turnId: string;
+  ts: number;
+  schemaVersion: typeof WORKHUB_COORDINATION_RECORD_SCHEMA_VERSION;
+  actionId: string;
+  actionFingerprint: `sha256:${string}`;
+  coordinationTurnId: string;
+  targetSessionId: string;
+  disposition: WorkHubDelegationDisposition;
+}
+
+/** Durable target choice written before a delegated Session effect is attempted. */
+export interface WorkHubDelegationIntentMessage extends WorkHubCoordinationMessageEnvelope {
+  kind: 'delegation_intent';
+}
+
+/** Durable proof that one Coordination action owns one accepted target Turn. */
+export interface WorkHubDelegationCommittedMessage extends WorkHubCoordinationMessageEnvelope {
+  kind: 'delegation_committed';
+  delegationId: string;
+  targetTurnId: string;
+  steered?: true;
+}
+
+export type WorkHubCoordinationMessage =
+  | WorkHubDelegationIntentMessage
+  | WorkHubDelegationCommittedMessage;
+
 export interface TurnRecord {
   turnId: string;
   firstSequence?: number;
@@ -1030,6 +1066,41 @@ const TURN_STATE_MESSAGE_SHAPE = defineObjectShape<TurnStateMessage>()(
     'errorClass',
   ],
 );
+const WORKHUB_DELEGATION_INTENT_MESSAGE_SHAPE = defineObjectShape<WorkHubDelegationIntentMessage>()(
+  [
+    'type',
+    'id',
+    'turnId',
+    'ts',
+    'schemaVersion',
+    'kind',
+    'actionId',
+    'actionFingerprint',
+    'coordinationTurnId',
+    'targetSessionId',
+    'disposition',
+  ],
+  [],
+);
+const WORKHUB_DELEGATION_COMMITTED_MESSAGE_SHAPE =
+  defineObjectShape<WorkHubDelegationCommittedMessage>()(
+    [
+      'type',
+      'id',
+      'turnId',
+      'ts',
+      'schemaVersion',
+      'kind',
+      'actionId',
+      'actionFingerprint',
+      'coordinationTurnId',
+      'targetSessionId',
+      'disposition',
+      'delegationId',
+      'targetTurnId',
+    ],
+    ['steered'],
+  );
 const SYSTEM_NOTE_MESSAGE_SHAPE = defineObjectShape<SystemNoteMessage>()(
   ['type', 'id', 'ts', 'kind'],
   ['turnId', 'data'],
@@ -1177,6 +1248,11 @@ function decodeMessage(
       )
         return message as unknown as TurnStateMessage;
       break;
+    case 'workhub_coordination':
+      if (isWorkHubCoordinationMessage(message)) {
+        return message as unknown as WorkHubCoordinationMessage;
+      }
+      break;
     case 'system_note':
       if (
         hasExactShape(message, SYSTEM_NOTE_MESSAGE_SHAPE) &&
@@ -1190,6 +1266,30 @@ function decodeMessage(
   throw new Error('Invalid stored message schema');
 }
 
+function isWorkHubCoordinationMessage(message: Record<string, unknown>): boolean {
+  const common =
+    hasMessageEnvelope(message, true) &&
+    message.schemaVersion === WORKHUB_COORDINATION_RECORD_SCHEMA_VERSION &&
+    typeof message.actionId === 'string' &&
+    typeof message.actionFingerprint === 'string' &&
+    /^sha256:[a-f0-9]{64}$/u.test(message.actionFingerprint) &&
+    typeof message.coordinationTurnId === 'string' &&
+    message.turnId === message.coordinationTurnId &&
+    typeof message.targetSessionId === 'string' &&
+    (message.disposition === 'delegate_existing' || message.disposition === 'create_new');
+  if (!common) return false;
+  if (message.kind === 'delegation_intent') {
+    return hasExactShape(message, WORKHUB_DELEGATION_INTENT_MESSAGE_SHAPE);
+  }
+  return (
+    message.kind === 'delegation_committed' &&
+    hasExactShape(message, WORKHUB_DELEGATION_COMMITTED_MESSAGE_SHAPE) &&
+    typeof message.delegationId === 'string' &&
+    typeof message.targetTurnId === 'string' &&
+    (message.steered === undefined || message.steered === true)
+  );
+}
+
 function decodeStoredMessageContent(
   value: unknown,
   decodeToolResultContent: (content: unknown) => ToolResultContent,

packages/core/src/thread-search.ts

@@ -465,6 +465,7 @@ export function threadSearchMatchKind(message: StoredMessage): ThreadSearchMatch
     case 'permission_decision':
     case 'token_usage':
     case 'turn_state':
+    case 'workhub_coordination':
     case 'system_note':
       throw new Error(`Message type ${message.type} is not searchable`);
   }
@@ -488,6 +489,8 @@ export function formatSearchResultSummary(message: StoredMessage): string {
       return '用量记录';
     case 'turn_state':
       return '回合状态';
+    case 'workhub_coordination':
+      return 'WorkHub 协调记录';
     case 'system_note':
       return '系统记录';
   }
@@ -543,6 +546,7 @@ export function collectSearchableText(message: StoredMessage): string | undefine
     case 'permission_decision':
     case 'token_usage':
     case 'turn_state':
+    case 'workhub_coordination':
     case 'system_note':
       // Excluded — not user-typed / not user-visible content.
       return undefined;