SPEC-46: the CLI is a client — sessions from the terminal, handoff as a command

.pnpm-store/v11/projects/739d8fce9f21779d2680f9e8d181f4ee

@@ -0,0 +1 @@
+../../../server

app/lib/store/models.dart

@@ -1124,6 +1124,9 @@ class Session {
     this.resumable = false,
     this.closed = false,
     this.orphaned = false,
+    this.parentId,
+    this.handoffReason,
+    this.origin,
     this.queued = const [],
   });
 
@@ -1171,6 +1174,18 @@ class Session {
   /// repo root (no recreate-worktree path).
   final bool orphaned;
 
+  /// SPEC-46 lineage (D10): the session this one was handed off / spawned from,
+  /// so the app can caption "handed off from …". Null for a session with no
+  /// parent (every session created before SPEC-46, and every app-spawned one).
+  final String? parentId;
+
+  /// SPEC-46 (D10): why the handoff happened, as written by the outgoing agent.
+  final String? handoffReason;
+
+  /// SPEC-46 (D10): which client created this session ("app"/"cli"/"agent").
+  /// Null on pre-SPEC-46 rows; a plain string so an unknown value never throws.
+  final String? origin;
+
   /// Messages submitted while the agent was busy that could not be steered into
   /// the running turn (SPEC-35), oldest first. They are delivered one per idle
   /// transition and can be cancelled until then.
@@ -1191,6 +1206,9 @@ class Session {
     bool? resumable,
     bool? closed,
     bool? orphaned,
+    String? parentId,
+    String? handoffReason,
+    String? origin,
     List<QueuedMessage>? queued,
   }) => Session(
     id: id,
@@ -1210,6 +1228,9 @@ class Session {
     resumable: resumable ?? this.resumable,
     closed: closed ?? this.closed,
     orphaned: orphaned ?? this.orphaned,
+    parentId: parentId ?? this.parentId,
+    handoffReason: handoffReason ?? this.handoffReason,
+    origin: origin ?? this.origin,
     queued: queued ?? this.queued,
   );
 }

app/lib/transport/codec.dart

@@ -269,6 +269,11 @@ class WireCodec {
           resumable: j['resumable'] == true,
           closed: j['closed'] == true,
           orphaned: j['orphaned'] == true,
+          parentId: j['parentId'] is String ? j['parentId'] as String : null,
+          handoffReason: j['handoffReason'] is String
+              ? j['handoffReason'] as String
+              : null,
+          origin: j['origin'] is String ? j['origin'] as String : null,
           queued: decodeQueued(j['queued']),
         ),
       );

app/lib/ui/home/session_tile.dart

@@ -131,6 +131,28 @@ class SessionTile extends ConsumerWidget {
                             ],
                           ),
                           const SizedBox(height: kSpace2),
+                          if (_handoffCaption(session) case final caption?) ...[
+                            Row(
+                              children: [
+                                Icon(
+                                  PhosphorIconsLight.arrowBendUpRight,
+                                  size: 12,
+                                  color: cs.outline,
+                                ),
+                                const SizedBox(width: kSpace4),
+                                Expanded(
+                                  child: Text(
+                                    caption,
+                                    maxLines: 1,
+                                    overflow: TextOverflow.ellipsis,
+                                    style: Theme.of(context).textTheme.bodySmall
+                                        ?.copyWith(color: cs.outline),
+                                  ),
+                                ),
+                              ],
+                            ),
+                            const SizedBox(height: kSpace2),
+                          ],
                           Text(
                             session.pending
                                 ? 'Send a message to create a branch'
@@ -168,6 +190,24 @@ class SessionTile extends ConsumerWidget {
       s == SessionStatus.awaitingApproval ||
       s == SessionStatus.error;
 
+  /// SPEC-46 D10: a session with lineage was handed off from another session,
+  /// so the row explains itself rather than appearing as a mystery title. The
+  /// caption renders whenever [Session.parentId] is set and never depends on
+  /// resolving the parent — which may be closed or simply not cached — and
+  /// carries the outgoing agent's reason when one was written.
+  static String? _handoffCaption(Session session) {
+    if (session.parentId == null) return null;
+    final reason = session.handoffReason?.trim();
+    // Lineage with no reason is not necessarily a handoff: `makit fork` (U4)
+    // branches a conversation natively and deliberately writes no reason, because
+    // a fork is not a handoff (D6). "Continued from" is true of both; claiming a
+    // handoff would mislabel every forked session in the one place the user meets
+    // it.
+    return reason == null || reason.isEmpty
+        ? 'Continued from another session'
+        : 'Handed off — $reason';
+  }
+
   /// Confirms the close, then requests it and only reports the row as
   /// dismissed once the server acknowledges. Returning false on failure keeps
   /// the row in place (the session is still in [sessionsProvider]), so a failed

app/lib/ui/widgets/srv_request_handler.dart

@@ -334,11 +334,18 @@ class _SrvRequestHandlerState extends ConsumerState<SrvRequestHandler>
       context: ctx,
       barrierDismissible: false,
       builder: (dctx) => AlertDialog(
+        // D14 made this dialog open-ended: the caption carries a whole handoff
+        // reason and the message is whatever the agent wrote. Unscrollable, a
+        // long prompt is text the user can neither finish reading nor scroll
+        // past to reach Deny/Approve — which trains them to answer without
+        // reading, the very thing captioning them was meant to prevent.
+        scrollable: true,
         title: Text(body['title']?.toString() ?? 'Confirm'),
         content: Column(
           mainAxisSize: MainAxisSize.min,
           crossAxisAlignment: CrossAxisAlignment.start,
           children: [
+            _PromptCaption(session: body['session']),
             Text(body['message']?.toString() ?? ''),
             if (body['preview'] != null) ...[
               const SizedBox(height: kSpace8),
@@ -387,15 +394,28 @@ class _SrvRequestHandlerState extends ConsumerState<SrvRequestHandler>
       context: ctx,
       barrierDismissible: false,
       builder: (dctx) => AlertDialog(
+        // Scrollable for the same reason as the permission prompt, and more so:
+        // an 8-line field sits under the caption here, with the keyboard up.
+        scrollable: true,
         title: Text(body['title']?.toString() ?? 'Input'),
-        content: TextField(
-          controller: controller,
-          autofocus: true,
-          minLines: multiline ? 3 : 1,
-          maxLines: multiline ? 8 : 1,
-          decoration: InputDecoration(
-            hintText: body['placeholder']?.toString(),
-          ),
+        // Captioned like a permission prompt (D14): D13 routes an elicitation up
+        // the same ladder, so this dialog can equally reach a phone that has
+        // never opened the session asking the question.
+        content: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            _PromptCaption(session: body['session']),
+            TextField(
+              controller: controller,
+              autofocus: true,
+              minLines: multiline ? 3 : 1,
+              maxLines: multiline ? 8 : 1,
+              decoration: InputDecoration(
+                hintText: body['placeholder']?.toString(),
+              ),
+            ),
+          ],
         ),
         actions: [
           TextButton(
@@ -493,3 +513,59 @@ class _SrvRequestHandlerState extends ConsumerState<SrvRequestHandler>
   @override
   Widget build(BuildContext context) => widget.child;
 }
+
+/// SPEC-46 D14 — a self-describing header for a prompt whose session the phone
+/// may never have subscribed to. Sourced entirely from the `srv.request`
+/// envelope's `session` block (title, agent/harness, handoff origin), never
+/// from cached store state, so a stranded prompt reached at rung 3 of the D13
+/// ladder is still attributable. Renders nothing when the block is absent
+/// (existing prompts are unchanged).
+class _PromptCaption extends StatelessWidget {
+  const _PromptCaption({required this.session});
+
+  final Object? session;
+
+  @override
+  Widget build(BuildContext context) {
+    final s = session;
+    if (s is! Map) return const SizedBox.shrink();
+    final title = s['title']?.toString();
+    final agent = s['agent']?.toString();
+    final handoffReason = s['handoffReason']?.toString();
+    if ((title == null || title.isEmpty) &&
+        (agent == null || agent.isEmpty) &&
+        (handoffReason == null || handoffReason.isEmpty)) {
+      return const SizedBox.shrink();
+    }
+
+    final theme = Theme.of(context);
+    final heading = [
+      if (title != null && title.isNotEmpty) title,
+      if (agent != null && agent.isNotEmpty) agent,
+    ].join('  ·  ');
+
+    return Padding(
+      padding: const EdgeInsets.only(bottom: kSpace12),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          if (heading.isNotEmpty)
+            Text(
+              heading,
+              style: theme.textTheme.labelLarge?.copyWith(
+                color: theme.colorScheme.primary,
+              ),
+            ),
+          if (handoffReason != null && handoffReason.isNotEmpty)
+            Text(
+              'Handed off: $handoffReason',
+              style: theme.textTheme.bodySmall?.copyWith(
+                color: theme.colorScheme.onSurfaceVariant,
+              ),
+            ),
+        ],
+      ),
+    );
+  }
+}

app/test/session_resumable_test.dart

@@ -49,4 +49,49 @@ void main() {
       expect(sessions!.single.closed, isTrue);
     });
   });
+
+  group('Session lineage fields (SPEC-46 D10)', () {
+    test(
+      'decodeSessions parses parentId, handoffReason, origin when present',
+      () {
+        final sessions = WireCodec.decodeSessions([
+          {
+            'id': 's1',
+            'projectId': 'p1',
+            'agent': 'codex',
+            'title': 'handed off',
+            'status': 'idle',
+            'policy': 'ask-on-risky',
+            'parentId': 'parent-1',
+            'handoffReason': 'out of context',
+            'origin': 'agent',
+          },
+        ]);
+        final s = sessions!.single;
+        expect(s.parentId, 'parent-1');
+        expect(s.handoffReason, 'out of context');
+        expect(s.origin, 'agent');
+      },
+    );
+
+    test(
+      'lineage defaults to null when absent (pre-SPEC-46 row, no throw)',
+      () {
+        final sessions = WireCodec.decodeSessions([
+          {
+            'id': 's2',
+            'projectId': 'p1',
+            'agent': 'pi',
+            'title': 'legacy',
+            'status': 'idle',
+            'policy': 'ask-on-risky',
+          },
+        ]);
+        final s = sessions!.single;
+        expect(s.parentId, isNull);
+        expect(s.handoffReason, isNull);
+        expect(s.origin, isNull);
+      },
+    );
+  });
 }