Merge #TASK-1254 gateway workflow thread type restore

Author: Pyiner

docs/design/task-1254-ios-cold-start-workflow-run-restore.md

@@ -0,0 +1,156 @@
+# Task 1254: iOS Restore Guard And Gateway Thread Type Consistency
+
+## Problem
+
+Build 108 includes `3557c4c3` (`Fix iOS home cold-start restore`). That patch
+made the iOS persisted last-opened restore path reject resolved workflow-run
+destinations and clear polluted restore defaults.
+
+The pending-intent theory is rejected. `pendingThreadId` is queued only by
+URL/widget route handling before the gateway is ready, so it is deferred user
+navigation, not automatic restore. Cold-start deep links to workflow runs must
+continue to open workflow runs, just like warm links.
+
+The current iOS restore path is also narrower than the second draft claimed:
+iOS cold-start restore resolves missing recent-list entries through
+`/api/threads/{id}`, and the app test below confirms that a workflow summary
+fetched from that endpoint is rejected and clears polluted restore state. iOS
+does not currently decode the `thread` or `session` summary blocks returned by
+`/api/threads/history`.
+
+There is still a real gateway contract bug worth fixing: gateway history detail
+summaries can report a stored workflow-run thread as `chat`. That is independent
+contract hygiene for clients and tools that do consume the history envelope, not
+a proven iOS cold-start root cause.
+
+## Evidence
+
+Rejected iOS candidate:
+
+- `queuePendingThreadLink` is reached through `openMobileRouteFromLink` and
+  `queuePendingMobileRoute`, which are triggered from `.onOpenURL`;
+- the pending route is in memory and not a persisted automatic restore source;
+- blocking it would break explicit workflow-run links during cold start.
+
+Confirmed iOS restore guard:
+
+- `GaryxMobileModel.restoreLastOpenedThread(id:)` consults recent in-memory
+  summaries, then refreshed recent threads, then `client().getThread(threadId:)`
+  (`/api/threads/{id}`);
+- every resolved summary goes through the existing restoration policy before the
+  app opens a destination;
+- `GaryxThreadTranscript` does not decode `/api/threads/history` `thread` or
+  `session` blocks, so that endpoint is not a current iOS restore input.
+
+Confirmed gateway contract split:
+
+- list summaries derive `thread_type` from stored `thread_kind` with a `chat`
+  fallback;
+- `/api/threads/{id}` metadata currently clones raw metadata and does not
+  normalize `thread_type`;
+- `/api/threads/history` derives both `thread_type` and `session_type` from
+  `infer_thread_type(thread_id)`, so a normal workflow-run id with stored
+  `thread_kind: workflow_run` comes back as `chat`;
+- the same fallback is inconsistent for legacy ids without `thread_kind`:
+  metadata/list treat them as `chat`, while history currently treats
+  `cron::...` as `cron`.
+
+Added deterministic regression coverage:
+
+- App coverage:
+  `GaryxLastOpenedWorkflowRestoreTests.testColdLaunchRestoreRejectsWorkflowRunFetchedAfterRecentListOmission`
+  uses the captured workflow fixture, starts with empty in-memory `threads`,
+  stubs empty recent/pins plus `/api/threads/{id}`, and verifies restore lands on
+  home and clears polluted defaults. This passes today and documents that the
+  direct iOS getThread fallback is not the current hole.
+- Gateway red test:
+  `api::tests::test_thread_history_detail_preserves_workflow_thread_type` seeds a
+  transcript-backed thread with `thread_kind: workflow_run`, calls
+  `/api/threads/history?thread_id=...`, and currently fails because
+  `thread.thread_type == "chat"` instead of `"workflow_run"`.
+- Gateway fallback red test:
+  `api::tests::test_thread_history_detail_defaults_missing_thread_kind_to_chat`
+  seeds a `cron::...` shaped legacy id without `thread_kind` and verifies history
+  defaults to `chat`, matching metadata/list behavior.
+- Metadata red tests:
+  `routes::tests::thread_metadata_preserves_workflow_thread_type` and
+  `routes::tests::thread_metadata_defaults_missing_thread_kind_to_chat` verify the
+  single-thread metadata response uses the same type derivation as history and
+  list summaries.
+
+## Design
+
+Introduce one gateway helper for thread-summary type derivation:
+
+```rust
+thread_kind_from_value(data).unwrap_or_else(|| "chat".to_owned())
+```
+
+Use that helper in all JSON summary surfaces that build from a raw thread record:
+
+- `routes::thread_summary(...)`, used by list/create/update style summaries;
+- `routes::thread_metadata_response(...)`, used by `/api/threads/{id}`;
+- `api::summarize_thread(...)`, used by `/api/threads/history` `thread` and
+  `session` envelopes.
+
+The helper deliberately has no id-pattern fallback. If old thread metadata lacks
+`thread_kind`, every raw-record summary surface reports `chat`. That matches the
+existing list fallback and eliminates the history-vs-metadata split for
+`cron::...` or group-shaped legacy ids without stored kind data.
+
+The fix is server-side because `thread_kind` is gateway/router state, and
+clients should not guess workflow identity from ids or workflow metadata side
+channels.
+
+## Why This Is Not A Patch
+
+The fix does not add an iOS-only `if workflow_run` guard and does not special
+case one cold-start branch. It makes the gateway surfaces that summarize the
+same raw thread record share the same type derivation and fallback.
+
+The iOS policy remains:
+
+- automatic persisted restore may open chat destinations only;
+- workflow-run and unresolved destinations clear polluted restore state and land
+  on home;
+- direct user opens, including cold-start deep links/widgets, may open workflow
+  runs.
+
+This design does not claim that `/api/threads/history` is the current iOS
+cold-start failure input. It preserves the existing iOS restore fix with app
+coverage and fixes an adjacent gateway contract bug that could mislead history
+consumers.
+
+## Validation Plan
+
+Before implementation:
+
+- Red gateway test:
+  `cargo test -p garyx-gateway test_thread_history_detail_preserves_workflow_thread_type -- --nocapture`
+  fails with `left: String("chat")`, `right: "workflow_run"`.
+- Red gateway fallback test:
+  `cargo test -p garyx-gateway test_thread_history_detail_defaults_missing_thread_kind_to_chat -- --nocapture`
+  fails because history reports `cron` for a `cron::...` id without
+  `thread_kind`.
+- Red metadata tests:
+  `cargo test -p garyx-gateway thread_metadata_preserves_workflow_thread_type -- --nocapture`
+  and
+  `cargo test -p garyx-gateway thread_metadata_defaults_missing_thread_kind_to_chat -- --nocapture`
+  fail because metadata does not normalize `thread_type`.
+- App getThread fallback coverage:
+  `xcodebuild test -project mobile/garyx-mobile/GaryxMobile.xcodeproj -scheme GaryxMobile -destination 'id=<simulator>' -only-testing:GaryxMobileTests/GaryxLastOpenedWorkflowRestoreTests/testColdLaunchRestoreRejectsWorkflowRunFetchedAfterRecentListOmission CODE_SIGNING_ALLOWED=NO`
+  passes and confirms that branch is already protected.
+
+After implementation:
+
+- Green gateway regressions above.
+- Green relevant gateway history tests:
+  `cargo test -p garyx-gateway thread_history_detail -- --nocapture`.
+- Green route metadata summary tests:
+  `cargo test -p garyx-gateway thread_metadata_ -- --nocapture`.
+- Green iOS restore tests:
+  `xcodebuild test -project mobile/garyx-mobile/GaryxMobile.xcodeproj -scheme GaryxMobile -destination 'id=<simulator>' -only-testing:GaryxMobileTests/GaryxLastOpenedWorkflowRestoreTests CODE_SIGNING_ALLOWED=NO`.
+- Green SwiftPM Core restore policy tests:
+  `swift test --package-path mobile/garyx-mobile --filter GaryxLastOpenedThreadRestorationPolicyTests`.
+- Real app-target compile:
+  `xcodebuild build -project mobile/garyx-mobile/GaryxMobile.xcodeproj -scheme GaryxMobile -destination 'id=<simulator>' CODE_SIGNING_ALLOWED=NO`.

garyx-gateway/src/api.rs

@@ -34,6 +34,7 @@ use crate::agent_teams::UpsertAgentTeamRequest;
 use crate::custom_agents::UpsertCustomAgentRequest;
 use crate::server::AppState;
 use crate::thread_runtime::{build_thread_runtime_summary, provider_type_from_key};
+use crate::thread_type::thread_summary_type_from_record;
 use crate::wikis::UpsertWikiRequest;
 
 // ---------------------------------------------------------------------------
@@ -1228,6 +1229,7 @@ pub(crate) async fn thread_history_for_key(
 
 fn summarize_thread(thread_id: &str, data: &Value, messages: &[Value]) -> Value {
     let message_count = history_message_count(data);
+    let thread_type = thread_summary_type_from_record(data);
 
     let last_user_message = last_message_content(messages, "user");
     let last_assistant_message = last_message_content(messages, "assistant");
@@ -1253,8 +1255,8 @@ fn summarize_thread(thread_id: &str, data: &Value, messages: &[Value]) -> Value
         "created_at": get_value("created_at", "_created_at"),
         "last_user_message": last_user_message,
         "last_assistant_message": last_assistant_message,
-        "session_type": infer_thread_type(thread_id),
-        "thread_type": infer_thread_type(thread_id),
+        "session_type": thread_type.clone(),
+        "thread_type": thread_type,
     })
 }
 
@@ -1280,16 +1282,6 @@ fn last_message_content(messages: &[Value], role: &str) -> Option<String> {
     None
 }
 
-fn infer_thread_type(thread_id: &str) -> &'static str {
-    if thread_id.starts_with("cron::") {
-        "cron"
-    } else if thread_id.contains("::group::") {
-        "group"
-    } else {
-        "chat"
-    }
-}
-
 fn raw_content_type_name(content: &Value) -> &'static str {
     match content {
         Value::Null => "null",

garyx-gateway/src/api/tests.rs

@@ -1122,6 +1122,81 @@ async fn test_thread_history_detail_with_thread_id_and_tool_messages() {
     assert_eq!(json["messages"][1]["message"]["content"], "world");
 }
 
+#[tokio::test]
+async fn test_thread_history_detail_preserves_workflow_thread_type() {
+    let state = test_state();
+    seed_transcript_backed_thread(
+        &state,
+        "thread::workflow-history",
+        json!({
+            "thread_kind": "workflow_run",
+            "workflow_run_id": "thread::workflow-history",
+            "workflow_definition_id": "test-workflow",
+            "label": "Synthetic workflow run",
+            "messages": [
+                {"role": "assistant", "content": "workflow output", "timestamp": "2026-03-01T00:00:01Z"}
+            ]
+        }),
+    )
+    .await;
+
+    let router = api_router(state);
+
+    let req = Request::builder()
+        .uri("/api/threads/history?thread_id=thread%3A%3Aworkflow-history&limit=10")
+        .body(Body::empty())
+        .unwrap();
+
+    let resp = router.oneshot(req).await.unwrap();
+    assert_eq!(resp.status(), 200);
+
+    let body = axum::body::to_bytes(resp.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let json: Value = serde_json::from_slice(&body).unwrap();
+    assert_eq!(json["ok"], true);
+    assert_eq!(json["thread"]["thread_type"], "workflow_run");
+    assert_eq!(json["session"]["thread_type"], "workflow_run");
+    assert_eq!(json["thread"]["session_type"], "workflow_run");
+    assert_eq!(json["session"]["session_type"], "workflow_run");
+}
+
+#[tokio::test]
+async fn test_thread_history_detail_defaults_missing_thread_kind_to_chat() {
+    let state = test_state();
+    seed_transcript_backed_thread(
+        &state,
+        "cron::legacy-history",
+        json!({
+            "label": "Legacy cron-shaped thread",
+            "messages": [
+                {"role": "assistant", "content": "legacy output", "timestamp": "2026-03-01T00:00:01Z"}
+            ]
+        }),
+    )
+    .await;
+
+    let router = api_router(state);
+
+    let req = Request::builder()
+        .uri("/api/threads/history?thread_id=cron%3A%3Alegacy-history&limit=10")
+        .body(Body::empty())
+        .unwrap();
+
+    let resp = router.oneshot(req).await.unwrap();
+    assert_eq!(resp.status(), 200);
+
+    let body = axum::body::to_bytes(resp.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let json: Value = serde_json::from_slice(&body).unwrap();
+    assert_eq!(json["ok"], true);
+    assert_eq!(json["thread"]["thread_type"], "chat");
+    assert_eq!(json["session"]["thread_type"], "chat");
+    assert_eq!(json["thread"]["session_type"], "chat");
+    assert_eq!(json["session"]["session_type"], "chat");
+}
+
 #[tokio::test]
 async fn test_thread_history_detail_pages_before_global_index() {
     let state = test_state();

garyx-gateway/src/automation.rs

@@ -16,9 +16,7 @@ use garyx_models::{Principal, TaskNotificationTarget};
 use garyx_router::{
     CreateTaskInput, FileTaskCounterStore, TaskRuntimeInput, TaskService, WorkspaceMode,
 };
-use garyx_router::{
-    history_message_count, is_thread_key, thread_kind_from_value, workspace_dir_from_value,
-};
+use garyx_router::{history_message_count, is_thread_key, workspace_dir_from_value};
 use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::{Value, json};
 use uuid::Uuid;
@@ -31,6 +29,7 @@ use crate::app_db::{
 use crate::cron::{CronJob, JobRunStatus, RunRecord};
 use crate::garyx_db::AutomationThreadRunRecord;
 use crate::server::AppState;
+use crate::thread_type::thread_summary_type_from_record;
 use crate::transcript_run_projection::active_run_id_from_transcript_store;
 
 const AUTOMATION_KEY_PREFIX: &str = "automation::";
@@ -1111,7 +1110,7 @@ fn automation_thread_summary(
     json!({
         "id": thread_id,
         "threadId": thread_id,
-        "threadType": thread_kind_from_value(data).unwrap_or_else(|| "chat".to_owned()),
+        "threadType": thread_summary_type_from_record(data),
         "title": title,
         "label": title,
         "workspaceDir": workspace_dir_from_value(data),

garyx-gateway/src/lib.rs

@@ -40,6 +40,7 @@ pub mod tasks;
 pub mod thread_logs;
 mod thread_meta_projection;
 mod thread_runtime;
+mod thread_type;
 mod tool_image;
 mod transcript_run_projection;
 mod wikis;

garyx-gateway/src/recent_thread_projection.rs

@@ -2,7 +2,7 @@ use async_trait::async_trait;
 use garyx_bridge::MultiProviderBridge;
 use garyx_router::{
     ThreadStore, ThreadStoreError, ThreadTranscriptStore, history_message_count,
-    is_hidden_thread_value, is_thread_key, thread_kind_from_value, workspace_dir_from_value,
+    is_hidden_thread_value, is_thread_key, workspace_dir_from_value,
 };
 use serde_json::Value;
 use std::sync::{Arc, Weak};
@@ -11,6 +11,7 @@ use tracing::warn;
 use crate::garyx_db::{GaryxDbService, RecentThreadDraft};
 use crate::task_projection::task_projection_draft_from_thread_data;
 use crate::thread_meta_projection::thread_meta_projection_from_thread_data_with_active_run;
+use crate::thread_type::thread_summary_type_from_record;
 use crate::transcript_run_projection::active_run_id_from_transcript_store;
 
 pub(crate) const RECENT_THREAD_MISSING_TIMESTAMP: &str = "1970-01-01T00:00:00.000Z";
@@ -429,7 +430,7 @@ fn recent_thread_draft_from_thread_data_with_active_run(
         .unwrap_or("New Thread")
         .to_owned();
     let workspace_dir = workspace_dir_from_value(data);
-    let thread_type = thread_kind_from_value(data).unwrap_or_else(|| "chat".to_owned());
+    let thread_type = thread_summary_type_from_record(data);
     let provider_type = data
         .get("provider_type")
         .and_then(Value::as_str)

garyx-gateway/src/routes.rs

@@ -24,8 +24,8 @@ use garyx_models::routing::{DELIVERY_TARGET_TYPE_CHAT_ID, DELIVERY_TARGET_TYPE_O
 use garyx_router::{
     ChannelBinding, KnownChannelEndpoint, THREAD_TRANSCRIPT_REPLAY_CAP, ThreadEnsureOptions,
     ThreadTranscriptRecord, WorkspaceMode, bindings_from_value, detach_endpoint_from_thread,
-    history_message_count, is_thread_key, thread_kind_from_value, update_thread_record,
-    workspace_dir_from_value, workspace_git_status as router_workspace_git_status,
+    history_message_count, is_thread_key, update_thread_record, workspace_dir_from_value,
+    workspace_git_status as router_workspace_git_status,
 };
 use serde::Deserialize;
 use serde_json::{Map, Value, json};
@@ -48,6 +48,7 @@ use crate::server::AppState;
 use crate::skills::SkillStoreError;
 use crate::thread_meta_projection::backfill_thread_meta_projection_if_incomplete;
 use crate::thread_runtime::build_thread_runtime_summary;
+use crate::thread_type::thread_summary_type_from_record;
 use crate::workspace_mode::{
     ensure_implicit_thread_workspace_for_config, worktree_base_dir_for_config,
 };
@@ -1372,7 +1373,7 @@ pub(crate) fn thread_summary(thread_id: &str, data: &Value) -> Value {
     json!({
         "thread_id": thread_id,
         "thread_key": thread_id,
-        "thread_type": thread_kind_from_value(data).unwrap_or_else(|| "chat".to_owned()),
+        "thread_type": thread_summary_type_from_record(data),
         "label": label,
         "workspace_dir": workspace_dir,
         "channel_bindings": channel_bindings,
@@ -1537,6 +1538,10 @@ async fn thread_metadata_response(state: &Arc<AppState>, thread_id: &str, data:
             .or_insert_with(|| Value::String(thread_id.to_owned()));
         obj.entry("thread_key".to_owned())
             .or_insert_with(|| Value::String(thread_id.to_owned()));
+        obj.insert(
+            "thread_type".to_owned(),
+            Value::String(thread_summary_type_from_record(data)),
+        );
         if let Some(block) = team_block {
             obj.insert("team".to_owned(), block);
         }