feat(mcp): read back thread pin, archive and auto-settle state

apps/server/src/mcp/OrchestratorMcpService.test.ts

@@ -3171,6 +3171,85 @@ describe("OrchestratorMcpService thread list", () => {
   );
 });
 
+describe("OrchestratorMcpService thread organization readback", () => {
+  const client: McpInvocationScope = {
+    environmentId: EnvironmentId.make("environment:thread-org"),
+    requestNamespace: "client:thread-org",
+    thread: undefined,
+    client: { sessionId: "thread-org", label: "Claude Code", access: "full-access" },
+    capabilities: new Set(["orchestration"]),
+    issuedAt: 1,
+  };
+  const pinnedAt = DateTime.makeUnsafe("2026-01-01T03:00:00.000Z");
+  const pinnedThreadId = ThreadId.make("thread:org-pinned");
+  const archivedThreadId = ThreadId.make("thread:org-archived");
+  const pinnedShell: OrchestrationV2ThreadShell = {
+    ...liveThreadShell(pinnedThreadId),
+    pinnedAt,
+    autoSettleDisabledAt: pinnedAt,
+  };
+  const archivedShell: OrchestrationV2ThreadShell = {
+    ...liveThreadShell(archivedThreadId),
+    archivedAt: pinnedAt,
+  };
+  // Stands in for the projection store's active/archive locations.
+  const service = layerOrchestratorService.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        Layer.mock(ThreadManagementService.ThreadManagementService)({
+          listProjectThreads: (input) =>
+            Effect.succeed(input.location === "archive" ? [archivedShell] : [pinnedShell]),
+          getThreadShell: () => Effect.succeed(pinnedShell),
+          getProjectThreadRecords: () => Effect.succeed(idleThreadProjection(pinnedShell)),
+          getTimelinePage: () => Effect.succeed({ items: [], totalItems: 0, hasMore: false }),
+        }),
+        ServerSettings.layerTest(),
+        Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
+        Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
+          list: () => Effect.succeed([]),
+        }),
+        Layer.mock(ProjectService.ProjectService)({}),
+        Layer.mock(SecretRequests.SecretRequests)({}),
+        unusedDelegationPolicyLayer,
+        Layer.mock(RemoteDelegation.RemoteDelegation)({}),
+        Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
+      ),
+    ),
+  );
+
+  it.effect("reads pin and auto-settle state back into list and detail", () =>
+    Effect.gen(function* () {
+      const mcp = yield* OrchestratorMcpService.OrchestratorMcpService;
+      const listed = yield* mcp.listThreads(client, { allProjects: true });
+      assert.equal(listed.threads.length, 1);
+      assert.equal(listed.threads[0]?.pinned, true);
+      assert.equal(listed.threads[0]?.autoSettle, false);
+      assert.equal(listed.threads[0]?.archived, false);
+      const read = yield* mcp.readThread(client, { threadId: pinnedThreadId });
+      assert.equal(read.thread.pinned, true);
+      assert.equal(read.thread.autoSettle, false);
+    }).pipe(Effect.provide(service)),
+  );
+
+  it.effect("lists archived threads only when asked", () =>
+    Effect.gen(function* () {
+      const mcp = yield* OrchestratorMcpService.OrchestratorMcpService;
+      const active = yield* mcp.listThreads(client, { allProjects: true });
+      assert.deepStrictEqual(
+        active.threads.map((thread) => thread.threadId),
+        [pinnedThreadId],
+      );
+      const archive = yield* mcp.listThreads(client, { allProjects: true, archived: true });
+      assert.deepStrictEqual(
+        archive.threads.map((thread) => thread.threadId),
+        [archivedThreadId],
+      );
+      assert.equal(archive.threads[0]?.archived, true);
+    }).pipe(Effect.provide(service)),
+  );
+});
+
 describe("OrchestratorMcpService thread stop", () => {
   const driver = ProviderDriverKind.make("codex");
   const instanceId = ProviderInstanceId.make("codex");

apps/server/src/mcp/OrchestratorMcpService.ts

@@ -775,6 +775,9 @@ function listItemFromShell(
     pullRequests: threadPullRequests(shell.pullRequests),
     ...threadSettlement(shell),
     ...threadSnooze(shell, nowMs),
+    pinned: shell.pinnedAt != null,
+    archived: shell.archivedAt !== null,
+    autoSettle: shell.autoSettleDisabledAt == null,
     lastVisitedAt: shell.lastVisitedAt != null ? DateTime.formatIso(shell.lastVisitedAt) : null,
     latestRunCompletedAt:
       shell.latestRunCompletedAt != null ? DateTime.formatIso(shell.latestRunCompletedAt) : null,
@@ -829,6 +832,8 @@ function threadDetail(
       (request) => request.status === "pending",
     ).length,
     archived: projection.thread.archivedAt !== null,
+    pinned: projection.thread.pinnedAt != null,
+    autoSettle: projection.thread.autoSettleDisabledAt == null,
     ...threadSettlement(projection.thread),
     ...threadSnooze(shell, nowMs),
     lastVisitedAt: shell.lastVisitedAt != null ? DateTime.formatIso(shell.lastVisitedAt) : null,
@@ -2842,6 +2847,7 @@ const make = Effect.gen(function* () {
         .listProjectThreads({
           projectId: projectId ?? undefined,
           includeSubagents: input.includeSubagents !== false,
+          location: input.archived ? "archive" : "active",
         })
         .pipe(
           Effect.mapError((error) =>

apps/server/src/mcp/toolkits/orchestrator/tools.ts

@@ -222,7 +222,7 @@ const CreateThreadsTool = Tool.make("create_threads", {
 
 const ThreadListTool = Tool.make("t3_thread_list", {
   description:
-    "List threads newest first, in one project or with `allProjects`. Page with `cursor`.",
+    "List threads newest first, in one project or with `allProjects`. `archived: true` lists the archive. Page with `cursor`.",
   parameters: OrchestratorMcpThreadListInput,
   success: OrchestratorMcpThreadListResult,
   failure: OrchestratorMcpFailure,

apps/server/src/orchestration-v2/ThreadManagementService.ts

@@ -406,10 +406,11 @@ export interface ThreadManagementServiceShape {
     Orchestrator.OrchestratorV2Error
   >;
   readonly getThreadShell: Orchestrator.OrchestratorV2["Service"]["getThreadShell"];
-  /** Omit `projectId` to list every project's threads. */
+  /** Omit `projectId` to list every project's threads. Default location is active threads. */
   readonly listProjectThreads: (input: {
     readonly projectId?: ProjectId | undefined;
     readonly includeSubagents: boolean;
+    readonly location?: "active" | "archive" | undefined;
   }) => Effect.Effect<ReadonlyArray<OrchestrationV2ThreadShell>, ThreadManagementError>;
   readonly sendToThread: (
     input: ThreadManagementSendInput,
@@ -755,7 +756,7 @@ const make = Effect.gen(function* () {
   const listProjectThreads: ThreadManagementServiceShape["listProjectThreads"] = (input) =>
     orchestrator
       .getShellSnapshot({
-        location: "active",
+        location: input.location ?? "active",
         ...(input.projectId === undefined ? {} : { projectId: input.projectId }),
       })
       .pipe(

apps/server/src/provider/agentContextBudget.json

@@ -1,5 +1,5 @@
 {
   "claudeSystemAppendBytes": 5135,
   "codexAdditionalContextBytes": 6865,
-  "mcpToolListJsonBytes": 61993
+  "mcpToolListJsonBytes": 62116
 }

packages/contracts/src/orchestratorMcp.ts

@@ -344,6 +344,9 @@ export const OrchestratorMcpThreadListInput = Schema.Struct({
   titleContains: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(256))),
   settled: Schema.optional(Schema.Boolean),
   snoozed: Schema.optional(Schema.Boolean),
+  archived: Schema.optional(
+    Schema.Boolean.annotate({ description: "List archived threads instead of active." }),
+  ),
   includeSubagents: Schema.optional(Schema.Boolean),
   cursor: Schema.optional(NonNegativeInt),
   limit: Schema.optional(PositiveInt.check(Schema.isLessThanOrEqualTo(100))),
@@ -378,6 +381,9 @@ export const OrchestratorMcpThreadListItem = Schema.Struct({
   settledAt: Schema.NullOr(IsoDateTime),
   snoozed: Schema.Boolean,
   snoozedUntil: Schema.NullOr(IsoDateTime),
+  pinned: Schema.Boolean,
+  archived: Schema.Boolean,
+  autoSettle: Schema.Boolean,
   lastVisitedAt: Schema.NullOr(IsoDateTime),
   latestRunCompletedAt: Schema.NullOr(IsoDateTime),
   parentThreadId: Schema.NullOr(ThreadId),
@@ -456,6 +462,8 @@ export const OrchestratorMcpThreadDetail = Schema.Struct({
   itemCount: NonNegativeInt,
   pendingRequestCount: NonNegativeInt,
   archived: Schema.Boolean,
+  pinned: Schema.Boolean,
+  autoSettle: Schema.Boolean,
   settled: Schema.Boolean,
   settledAt: Schema.NullOr(IsoDateTime),
   snoozed: Schema.Boolean,