feat(issue-status): Phase 1 schema + built-in status seeding (MUL-4809)

packages/core/api/client.ts

@@ -564,6 +564,8 @@ export class ApiClient {
     if (params?.workspace_id) search.set("workspace_id", params.workspace_id);
     if (params?.q?.trim()) search.set("q", params.q.trim());
     if (params?.status) search.set("status", params.status);
+    if (params?.status_id) search.set("status_id", params.status_id);
+    if (params?.status_category) search.set("status_category", params.status_category);
     if (params?.statuses?.length) search.set("statuses", params.statuses.join(","));
     if (params?.priority) search.set("priority", params.priority);
     if (params?.priorities?.length) search.set("priorities", params.priorities.join(","));
@@ -627,6 +629,8 @@ export class ApiClient {
     if (params.offset) search.set("offset", String(params.offset));
     if (params.workspace_id) search.set("workspace_id", params.workspace_id);
     if (params.statuses?.length) search.set("statuses", params.statuses.join(","));
+    if (params.status_id) search.set("status_id", params.status_id);
+    if (params.status_category) search.set("status_category", params.status_category);
     if (params.priorities?.length) search.set("priorities", params.priorities.join(","));
     if (params.assignee_types?.length) search.set("assignee_types", params.assignee_types.join(","));
     if (params.assignee_id) search.set("assignee_id", params.assignee_id);

packages/core/api/schema.test.ts

@@ -91,6 +91,122 @@ describe("ApiClient schema fallback", () => {
     });
   });
 
+  describe("listIssues status_detail (MUL-4809)", () => {
+    // Minimal valid issue row (only the non-defaulted fields).
+    const baseIssue = {
+      id: "issue-1",
+      workspace_id: "ws-1",
+      number: 1,
+      identifier: "MUL-1",
+      title: "Test",
+      description: null,
+      status: "todo",
+      priority: "none",
+      assignee_type: null,
+      assignee_id: null,
+      creator_type: "member",
+      creator_id: "user-1",
+      parent_issue_id: null,
+      project_id: null,
+      position: 1,
+      start_date: null,
+      due_date: null,
+      created_at: "2026-01-01T00:00:00Z",
+      updated_at: "2026-01-01T00:00:00Z",
+    };
+
+    it("parses an old-server issue that omits status_id / status_detail", async () => {
+      // Older backends predate MUL-4809 and send neither field. Must parse, not
+      // fall back, and leave the client on the legacy `status` token.
+      stubFetchJson({ issues: [baseIssue], total: 1 });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res.issues).toHaveLength(1);
+      expect(res.issues[0]?.status_id).toBeUndefined();
+      expect(res.issues[0]?.status_detail).toBeUndefined();
+      expect(res.issues[0]?.status).toBe("todo");
+    });
+
+    it("passes a well-formed status_id / status_detail through", async () => {
+      stubFetchJson({
+        issues: [
+          {
+            ...baseIssue,
+            status_id: "st-1",
+            status_detail: {
+              id: "st-1",
+              name: "In Review",
+              category: "in_progress",
+              icon: "in_review",
+              color: "success",
+            },
+          },
+        ],
+        total: 1,
+      });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res.issues[0]?.status_id).toBe("st-1");
+      expect(res.issues[0]?.status_detail?.name).toBe("In Review");
+      expect(res.issues[0]?.status_detail?.category).toBe("in_progress");
+    });
+
+    it("degrades status_detail to null on an unknown category, keeping the issue", async () => {
+      // category is a closed 5-value set. An unknown value must fail only the
+      // status_detail field (-> null), never blank the issue or the whole list.
+      stubFetchJson({
+        issues: [
+          {
+            ...baseIssue,
+            status_id: "st-1",
+            status_detail: {
+              id: "st-1",
+              name: "Weird",
+              category: "some_future_category",
+              icon: "todo",
+              color: "warning",
+            },
+          },
+        ],
+        total: 1,
+      });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res.issues).toHaveLength(1);
+      expect(res.issues[0]?.status).toBe("todo");
+      expect(res.issues[0]?.status_detail).toBeNull();
+    });
+
+    it("degrades a malformed status_detail to null without blanking the list (§7.3)", async () => {
+      // A wrong-typed subfield used to fail the outer IssueSchema and drop the
+      // whole batch to []. Now it degrades to just status_detail = null.
+      stubFetchJson({
+        issues: [
+          { ...baseIssue, id: "issue-1", status_detail: { id: 123, name: null } },
+          { ...baseIssue, id: "issue-2" },
+        ],
+        total: 2,
+      });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res.issues).toHaveLength(2);
+      expect(res.issues[0]?.status_detail).toBeNull();
+      expect(res.issues[0]?.status).toBe("todo");
+    });
+
+    it("keeps null on explicit-null status_id / status_detail", async () => {
+      stubFetchJson({
+        issues: [{ ...baseIssue, status_id: null, status_detail: null }],
+        total: 1,
+      });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res.issues).toHaveLength(1);
+      expect(res.issues[0]?.status_id).toBeNull();
+      expect(res.issues[0]?.status_detail).toBeNull();
+    });
+  });
+
   describe("createIssue", () => {
     // The create modal decides whether to run its label-attach fallback by
     // reading `labels` off the parsed response, and treats a rejection as a

packages/core/api/schemas.ts

@@ -435,6 +435,20 @@ export const IssueTriggerPreviewSchema = z.object({
 // to {} so consumers never need to nil-guard `issue.metadata`.
 const IssueMetadataSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({});
 
+// Resolved catalog view of an issue's status (MUL-4809). Unlike the open string
+// enums elsewhere in this file, `category` is a CLOSED 5-value set by product
+// design (no 6th Category is ever added), so it is a strict enum here — that
+// keeps the public StatusDetail.category union honest, and a malformed/unknown
+// value fails this schema and is degraded to null at the field (see IssueSchema),
+// never blanking the whole issue. `.loose()` still preserves extra server fields.
+export const StatusDetailSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  category: z.enum(["backlog", "todo", "in_progress", "done", "cancelled"]),
+  icon: z.string(),
+  color: z.string(),
+}).loose();
+
 export const IssueSchema = z.object({
   id: z.string(),
   workspace_id: z.string(),
@@ -462,6 +476,14 @@ export const IssueSchema = z.object({
   properties: IssuePropertyValuesSchema,
   reactions: z.array(z.unknown()).optional(),
   labels: z.array(z.unknown()).optional(),
+  // Custom-status catalog fields (MUL-4809). Optional (absent on older backends
+  // and on endpoints that don't hydrate them) + nullable (null when the issue has
+  // no status_id yet). `.catch(null)` isolates malformed data to THIS field —
+  // a bad status_id/status_detail degrades to null and the issue (and the whole
+  // list) still parses, per the §7.3 safe-degrade rule — the client then falls
+  // back to the legacy `status` token.
+  status_id: z.string().nullish().catch(null),
+  status_detail: StatusDetailSchema.nullish().catch(null),
   created_at: z.string(),
   updated_at: z.string(),
 }).loose();

packages/core/types/api.ts

@@ -1,4 +1,4 @@
-import type { Issue, IssueMetadata, IssueStatus, IssuePriority, IssueAssigneeType } from "./issue";
+import type { Issue, IssueMetadata, IssueStatus, IssuePriority, IssueAssigneeType, StatusCategory } from "./issue";
 import type { MemberRole } from "./workspace";
 import type { Project } from "./project";
 
@@ -83,6 +83,10 @@ export interface ListIssuesParams {
   /** Flat-table quick search. Matches issue title words or an exact issue number. */
   q?: string;
   status?: IssueStatus;
+  /** Exact custom-status filter by catalog id (MUL-4809). */
+  status_id?: string;
+  /** Filter by one of the 5 status Categories (MUL-4809). */
+  status_category?: StatusCategory;
   /** Multi-value table facet. OR within the field. */
   statuses?: IssueStatus[];
   priority?: IssuePriority;
@@ -163,6 +167,10 @@ export interface ListGroupedIssuesParams {
   offset?: number;
   workspace_id?: string;
   statuses?: IssueStatus[];
+  /** Exact custom-status filter by catalog id (MUL-4809). */
+  status_id?: string;
+  /** Filter by one of the 5 status Categories (MUL-4809). */
+  status_category?: StatusCategory;
   priorities?: IssuePriority[];
   assignee_types?: IssueAssigneeType[];
   assignee_id?: string;

packages/core/types/issue.ts

@@ -10,6 +10,28 @@ export type IssueStatus =
   | "blocked"
   | "cancelled";
 
+// The 5 immutable status Categories — the only machine-readable status semantics
+// in the custom-status model (MUL-4809). A custom or built-in status belongs to
+// exactly one Category; automation branches on the Category, never the name.
+export type StatusCategory =
+  | "backlog"
+  | "todo"
+  | "in_progress"
+  | "done"
+  | "cancelled";
+
+// StatusDetail is the resolved catalog view of an issue's status, attached to
+// issue responses by list/detail endpoints (MUL-4809). Optional/nullable: absent
+// or null when the issue has no status_id yet — callers fall back to the legacy
+// `status` token. name/icon/color are human-facing; category is the machine key.
+export interface StatusDetail {
+  id: string;
+  name: string;
+  category: StatusCategory;
+  icon: string;
+  color: string;
+}
+
 export type IssuePriority = "urgent" | "high" | "medium" | "low" | "none";
 
 export type IssueAssigneeType = "member" | "agent" | "squad";
@@ -64,6 +86,12 @@ export interface Issue {
   properties: IssuePropertyValues;
   reactions?: IssueReaction[];
   labels?: Label[];
+  // Authoritative custom-status catalog id + resolved detail (MUL-4809),
+  // bulk-attached by list/detail endpoints like `labels`. Absent/null when the
+  // issue has no status_id yet or on paths that don't hydrate them; the legacy
+  // `status` field stays the fallback.
+  status_id?: string | null;
+  status_detail?: StatusDetail | null;
   created_at: string;
   updated_at: string;
 }

server/cmd/server/autopilot_dispatch_for_plan_test.go

@@ -190,8 +190,8 @@ func TestDispatchAutopilotSuppressesRecentDuplicateIssue(t *testing.T) {
 	if err != nil {
 		t.Fatalf("first DispatchAutopilot: %v", err)
 	}
-	if first == nil || first.Status != "issue_created" || !first.IssueID.Valid {
-		t.Fatalf("first dispatch = %+v, want issue_created with issue_id", first)
+	if first == nil || first.Status != "running" || !first.IssueID.Valid || !first.TaskID.Valid {
+		t.Fatalf("first dispatch = %+v, want running with issue_id + task_id (MUL-4809 §4.1)", first)
 	}
 
 	second, err := autopilotSvc.DispatchAutopilot(ctx, ap, pgtype.UUID{}, "manual", nil)

server/cmd/server/autopilot_listeners.go

@@ -2,48 +2,19 @@ package main
 
 import (
 	"context"
-	"log/slog"
 
 	"github.com/multica-ai/multica/server/internal/events"
-	"github.com/multica-ai/multica/server/internal/handler"
 	"github.com/multica-ai/multica/server/internal/service"
 	"github.com/multica-ai/multica/server/pkg/protocol"
 )
 
-// registerAutopilotListeners hooks into issue and task events to keep
-// autopilot runs in sync with their linked issues and tasks.
+// registerAutopilotListeners hooks into task terminal events to keep autopilot
+// runs in sync with the task each run dispatched. Runs are finalized purely by
+// task outcome (MUL-4809 §4.1) — issue status no longer ends or fails a run, so
+// there is no EventIssueUpdated subscription here anymore.
 func registerAutopilotListeners(bus *events.Bus, svc *service.AutopilotService) {
 	ctx := context.Background()
 
-	// When an issue with origin_type='autopilot' reaches a terminal status,
-	// update the corresponding autopilot run.
-	bus.Subscribe(protocol.EventIssueUpdated, func(e events.Event) {
-		payload, ok := e.Payload.(map[string]any)
-		if !ok {
-			return
-		}
-		statusChanged, _ := payload["status_changed"].(bool)
-		if !statusChanged {
-			return
-		}
-		issue, ok := payload["issue"].(handler.IssueResponse)
-		if !ok {
-			return
-		}
-		// Only handle statuses that finalize an autopilot run.
-		if issue.Status != "done" && issue.Status != "in_review" && issue.Status != "cancelled" && issue.Status != "blocked" {
-			return
-		}
-		// Load the full issue from DB to check origin_type.
-		dbIssue, err := svc.Queries.GetIssue(ctx, parseUUID(issue.ID))
-		if err != nil {
-			slog.Debug("autopilot listener: failed to load issue", "issue_id", issue.ID, "error", err)
-			return
-		}
-		svc.SyncRunFromIssue(ctx, dbIssue)
-	})
-
-	// When a task completes or fails, check if it's an autopilot run_only task.
 	bus.Subscribe(protocol.EventTaskCompleted, func(e events.Event) {
 		syncRunFromTaskEvent(ctx, svc, e)
 	})
@@ -68,11 +39,11 @@ func syncRunFromTaskEvent(ctx context.Context, svc *service.AutopilotService, e
 	if err != nil {
 		return
 	}
+	// run_only tasks carry autopilot_run_id; create_issue tasks carry only
+	// issue_id and are matched to their run via run.task_id + retry lineage.
 	if task.AutopilotRunID.Valid {
 		svc.SyncRunFromTask(ctx, task)
 		return
 	}
-	if e.Type == protocol.EventTaskFailed {
-		svc.SyncRunFromLinkedIssueTask(ctx, task)
-	}
+	svc.SyncRunFromCreateIssueTask(ctx, task)
 }