Skip to content

Commit 8261376

Browse files
donjor-agent[bot]rsi-pr-agent
authored andcommitted
feat(server): threads persist linked GitHub issues (#1440)
## What Changed A thread stores its linked GitHub issues as orchestration state, modeled on its pull request links. ### Model - **Link:** host, repository, number, url - **Record:** source (`manual`, `handoff`, `agent`), `linkedAt` - **Snapshot:** title, state, `syncedAt` - **Commands:** `thread.issue.link`, `thread.issue.unlink` - **Sync:** internal `thread.issue-link.sync` - **Capability:** `threadIssues`, missing means unsupported - **Reverse lookup:** RPC for the threads on one issue ### Storage and reads - **Table:** idempotent `ForkSchema.ts` pass, never a numbered migration - **Thread and shell:** optional `issues`, omitted when empty - **Live:** shell subscribers refetch on a link change - **Detail stream:** carries no issue events - **Sync order:** an older snapshot never wins - **Deletion:** a re-created thread has no links Upstream files change only by one-line `fork-hook` lines; logic lives in `*.fork.ts`. ## Why Threads link pull requests but not the issues they work on. This is layer 1 of #1430: the web controls, MCP tools, sync and mobile build on it. ### Version skew | Client | Server | Result | | --- | --- | --- | | Old | New | decodes thread, shell and every stream item | | New | Old | missing `issues` reads as none; capability off | A server from before this change cannot reopen a database holding link events; `fork-delta.md` records that downgrade limit. ## Checks ```text tsc --noEmit (contracts, server, web, client-runtime, mobile) → exit 0 vp test run src/server.test.ts → exit 0 (211 tests) vp test run threadIssues + orchestration (contracts) → exit 0 (68 tests) vp test run 10 server files → exit 1 (146/147) vp run fork:ci → exit 0 ``` The one failure is `ServerEnvironment.fork.test` on this machine: the local service launcher started a different t3 version. CI is the authority for it. ## Evidence A second client holds a live shell subscription on a dev server running a snapshot copy of real data. The driver speaks the WebSocket RPC the clients use. 1. Link issues 1430 and 1431 on a real thread 2. Live shell update carries both links 3. Reverse lookup returns the thread 4. Duplicate link: rejected, no event, no update 5. Unlink 1430: live update drops it 6. Read-only database: projection row and events 7. Unlink 1431: `issues` key gone ![evidence-1440.gif](https://github.com/user-attachments/assets/770e9f45-7ff0-4d78-b58c-a9aecb88e6fc) <details> <summary>Stills</summary> ![evidence-1440-frame.png](https://github.com/user-attachments/assets/5e70a508-cf19-4a10-b877-804051efe5c4) ![evidence-1440-final.png](https://github.com/user-attachments/assets/fed5280e-60c7-4152-87e4-a9ca8fab5374) </details> ## Close conditions Refs #1431 - [x] Replay: events rebuild the same projection - [x] Stale sync: older than linkedAt is ignored - [x] Duplicate: linking twice is a no-op - [x] Re-link: works after an unlink - [x] Authorization: only readable threads return - [x] Deletion: deleted thread leaves the lookup - [ ] Gate: no link control without capability | Condition | Evidence | | --- | --- | | Replay, re-link, deletion | "link, sync, unlink, re-link and delete agree across every projection" | | Stale sync | "both projectors drop a sync for a removed link, an earlier link, or an older read" | | Duplicate | decider rejects it, no event; state unchanged | | Authorization | orchestration read scope, beside the pull request lookup | | Gate | server advertises `threadIssues`; the control lands with #1432, so this PR refs, not closes | ## Checklist - [x] This PR is small and focused - [x] I explained what changed and why - [x] I included before/after screenshots for any UI changes - [x] I included a video for animation/interaction changes No UI changes; the recording above is server evidence. Opus 5.5 via Claude Code in T3 Code. ## Fork trailers Squashes: - 68809f6 feat(server): threads persist linked GitHub issues (#1440) (#1440) (#1584) - 4af452c fixup! feat(server): threads persist linked GitHub issues (#1440) (#1440) - 50fce2b feat(server): threads persist linked GitHub issues (#1440) (#1440) (#1584) - 5510f5b fixup! feat(server): threads persist linked GitHub issues (#1440) (#1440) - b06fe75 feat(server): threads persist linked GitHub issues (#1440) (#1440) (#1584) - b4d8082 feat(issues): threads keep linked issues on Orchestrator V2 thread state - 0530808 feat(issues): the legacy importer carries V1 issue links onto V2 threads Fork-Domain: github-issues Fork-Tier: qol Fork-Upstreamable: no
1 parent 45cadb1 commit 8261376

29 files changed

Lines changed: 2392 additions & 11 deletions

‎apps/server/src/auth/RpcAuthorization.fork.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,8 @@ describe("RPC authorization scopes", () => {
99
expect(requiredScopeForRpcMethod(WS_METHODS.githubIssuesDetail)).toBe(
1010
AuthOrchestrationReadScope,
1111
);
12+
expect(requiredScopeForRpcMethod(WS_METHODS.githubIssuesLinkedThreads)).toBe(
13+
AuthOrchestrationReadScope,
14+
);
1215
});
1316
});

‎apps/server/src/auth/RpcAuthorization.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ export const RPC_REQUIRED_SCOPES = {
147147
[WS_METHODS.pullRequestsLabelCandidates]: AuthOrchestrationReadScope,
148148
[WS_METHODS.githubIssuesList]: AuthOrchestrationReadScope, // fork-hook: github-issues/rpc-auth-list
149149
[WS_METHODS.githubIssuesDetail]: AuthOrchestrationReadScope, // fork-hook: github-issues/rpc-auth-detail
150+
[WS_METHODS.githubIssuesLinkedThreads]: AuthOrchestrationReadScope, // fork-hook: github-issues/rpc-auth-linked-threads
150151
[WS_METHODS.sourceControlLookupRepository]: AuthOrchestrationReadScope,
151152
[WS_METHODS.subscribeProjectClones]: AuthOrchestrationReadScope,
152153
[WS_METHODS.projectsListEntries]: AuthFilesystemReadScope,

‎apps/server/src/environment/ServerEnvironment.fork.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ it.layer(NodeServices.layer)("ServerEnvironment fork", (it) => {
3131
}).pipe(Effect.provide(makeServerEnvironmentLayer(baseDir)));
3232

3333
expect(descriptor.capabilities.githubIssues).toBe(true);
34+
expect(descriptor.capabilities.threadIssues).toBe(true);
3435
}),
3536
);
3637
});

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ export const make = Effect.gen(function* () {
222222
pullRequests: true,
223223
githubIssues: true, // fork-hook: github-issues/server-environment-capability
224224
pullRequestChecks: true,
225+
threadIssues: true, // fork-hook: github-issues/server-environment-thread-issues-capability
225226
inlineMessageContext: true,
226227
requiredWorktreeBootstrap: true,
227228
threadSettlement: true,

‎apps/server/src/githubIssue/githubIssueWiring.fork.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,17 @@
66
// friends.
77
import * as Effect from "effect/Effect";
88
import * as Layer from "effect/Layer";
9+
import * as SqlClient from "effect/unstable/sql/SqlClient";
910
import type {
1011
EnvironmentAuthorizationError,
1112
GitHubIssueListInput,
1213
GitHubIssueRef,
14+
ThreadIssueKey,
1315
} from "@t3tools/contracts";
1416

1517
import * as GitHubCli from "../sourceControl/GitHubCli.ts";
1618
import * as GitHubIssueService from "./GitHubIssueService.ts";
19+
import { listLinkedIssueThreadsFork } from "./linkedThreads.fork.ts";
1720
import * as VcsProcess from "../vcs/VcsProcess.ts";
1821

1922
type ObserveRpcEffect = <A, E, R>(
@@ -31,6 +34,7 @@ type GitHubIssues = typeof GitHubIssueService.GitHubIssueService.Service;
3134
export const gitHubIssueRpcHandlersFork = (
3235
githubIssues: GitHubIssues,
3336
observeRpcEffect: ObserveRpcEffect,
37+
sql: SqlClient.SqlClient,
3438
) => ({
3539
"githubIssues.list": (input: GitHubIssueListInput) =>
3640
observeRpcEffect("githubIssues.list", githubIssues.list(input), {
@@ -40,6 +44,12 @@ export const gitHubIssueRpcHandlersFork = (
4044
observeRpcEffect("githubIssues.detail", githubIssues.detail(input), {
4145
"rpc.aggregate": "github-issues",
4246
}),
47+
"githubIssues.linkedThreads": (input: ThreadIssueKey) =>
48+
observeRpcEffect(
49+
"githubIssues.linkedThreads",
50+
listLinkedIssueThreadsFork(input).pipe(Effect.provideService(SqlClient.SqlClient, sql)),
51+
{ "rpc.aggregate": "github-issues" },
52+
),
4353
});
4454

4555
/** The upstream-shaped service layer, composed with its own dependencies. */
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
import { expect, it } from "@effect/vitest";
2+
import * as Effect from "effect/Effect";
3+
import * as Schema from "effect/Schema";
4+
import * as SqlClient from "effect/unstable/sql/SqlClient";
5+
6+
import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";
7+
import { listLinkedIssueThreadsFork } from "./linkedThreads.fork.ts";
8+
9+
const encodePayload = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
10+
11+
it.effect("finds every readable thread linked to exactly one issue, across projects, by host", () =>
12+
Effect.gen(function* () {
13+
const sql = yield* SqlClient.SqlClient;
14+
const createdAt = "2026-09-01T00:00:00.000Z";
15+
const laterAt = "2026-09-03T00:00:00.000Z";
16+
const fixtures = [
17+
{
18+
id: "active",
19+
projectId: "project-1",
20+
host: "github.com",
21+
repository: "acme/web",
22+
number: 7,
23+
},
24+
{
25+
id: "archived",
26+
projectId: "project-2",
27+
host: "github.com",
28+
repository: "acme/web",
29+
number: 7,
30+
},
31+
{
32+
id: "deleted",
33+
projectId: "project-1",
34+
host: "github.com",
35+
repository: "acme/web",
36+
number: 7,
37+
},
38+
{
39+
id: "enterprise",
40+
projectId: "project-1",
41+
host: "github.example.com",
42+
repository: "acme/web",
43+
number: 7,
44+
},
45+
{
46+
id: "other-repo",
47+
projectId: "project-1",
48+
host: "github.com",
49+
repository: "acme/api",
50+
number: 7,
51+
},
52+
{
53+
id: "other-number",
54+
projectId: "project-1",
55+
host: "github.com",
56+
repository: "acme/web",
57+
number: 8,
58+
},
59+
];
60+
for (const fixture of fixtures) {
61+
const payload = yield* encodePayload({
62+
issues: [
63+
{
64+
host: fixture.host,
65+
repository: fixture.repository,
66+
number: fixture.number,
67+
url: `https://${fixture.host}/${fixture.repository}/issues/${fixture.number}`,
68+
source: "manual",
69+
linkedAt: createdAt,
70+
snapshot: null,
71+
},
72+
],
73+
});
74+
yield* sql`
75+
INSERT INTO orchestration_v2_projection_threads (
76+
thread_id, project_id, title, default_provider, runtime_mode, interaction_mode,
77+
created_at, updated_at, archived_at, deleted_at, payload_json
78+
) VALUES (
79+
${fixture.id}, ${fixture.projectId}, ${fixture.id}, 'codex', 'full-access', 'default',
80+
${createdAt}, ${fixture.id === "archived" ? laterAt : createdAt},
81+
${fixture.id === "archived" ? laterAt : null},
82+
${fixture.id === "deleted" ? laterAt : null}, ${payload}
83+
)
84+
`;
85+
}
86+
// A thread from before issue links has no `issues` key at all.
87+
yield* sql`
88+
INSERT INTO orchestration_v2_projection_threads (
89+
thread_id, project_id, title, default_provider, runtime_mode, interaction_mode,
90+
created_at, updated_at, payload_json
91+
) VALUES (
92+
'pre-feature', 'project-1', 'pre-feature', 'codex', 'full-access', 'default',
93+
${createdAt}, ${createdAt}, '{"pullRequests":[]}'
94+
)
95+
`;
96+
97+
expect(
98+
yield* listLinkedIssueThreadsFork({ host: "GitHub.com", repository: "ACME/Web", number: 7 }),
99+
).toEqual({
100+
threads: [
101+
{ id: "archived", projectId: "project-2", title: "archived", archivedAt: laterAt },
102+
{ id: "active", projectId: "project-1", title: "active", archivedAt: null },
103+
],
104+
});
105+
expect(
106+
(yield* listLinkedIssueThreadsFork({
107+
host: "github.example.com",
108+
repository: "acme/web",
109+
number: 7,
110+
})).threads.map((thread) => thread.id),
111+
).toEqual(["enterprise"]);
112+
expect(
113+
yield* listLinkedIssueThreadsFork({ host: "github.com", repository: "acme/web", number: 9 }),
114+
).toEqual({ threads: [] });
115+
}).pipe(Effect.provide(SqlitePersistenceMemory)),
116+
);
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Fork-only reverse lookup for thread ↔ GitHub issue links, mirroring upstream's pull request
2+
// `linkedThreads.ts`: links live in the V2 thread payload's `issues` array. The key is
3+
// host-qualified, so one issue linked from two projects answers with both threads; deleted
4+
// threads are never returned.
5+
import {
6+
GitHubIssueOperationError,
7+
PullRequestLinkedThreadsResult,
8+
type ThreadIssueKey,
9+
} from "@t3tools/contracts";
10+
import * as Effect from "effect/Effect";
11+
import * as Schema from "effect/Schema";
12+
import * as SqlClient from "effect/unstable/sql/SqlClient";
13+
14+
import {
15+
normalizeThreadIssueKey,
16+
threadIssueKeysEqual,
17+
} from "../orchestration-v2/ThreadIssues.fork.ts";
18+
19+
const decodeLinkedThreads = Schema.decodeUnknownEffect(PullRequestLinkedThreadsResult);
20+
21+
export const listLinkedIssueThreadsFork = Effect.fn("listLinkedIssueThreadsFork")(
22+
function* (input: ThreadIssueKey) {
23+
const key = normalizeThreadIssueKey(input);
24+
const sql = yield* SqlClient.SqlClient;
25+
const rows = yield* sql<{
26+
id: string;
27+
projectId: string;
28+
title: string;
29+
archivedAt: string | null;
30+
host: string;
31+
repository: string;
32+
number: number;
33+
}>`
34+
SELECT t.thread_id AS id, t.project_id AS "projectId", t.title,
35+
t.archived_at AS "archivedAt", json_extract(link.value, '$.host') AS host,
36+
json_extract(link.value, '$.repository') AS repository,
37+
json_extract(link.value, '$.number') AS number
38+
FROM orchestration_v2_projection_threads AS t
39+
JOIN json_each(t.payload_json, '$.issues') AS link
40+
WHERE json_extract(link.value, '$.number') = ${key.number}
41+
AND t.deleted_at IS NULL
42+
ORDER BY t.updated_at DESC, t.thread_id ASC
43+
`;
44+
const threads = rows
45+
.filter((row) => threadIssueKeysEqual(row, key))
46+
.map(({ id, projectId, title, archivedAt }) => ({ id, projectId, title, archivedAt }));
47+
return yield* decodeLinkedThreads({ threads });
48+
},
49+
Effect.mapError(
50+
(cause) =>
51+
new GitHubIssueOperationError({
52+
operation: "linkedThreads",
53+
detail: "Could not load linked threads.",
54+
cause,
55+
}),
56+
),
57+
);

‎apps/server/src/orchestration-v2/Orchestrator.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,7 @@ import {
166166
ThreadForkServiceV2,
167167
} from "./ThreadForkService.ts";
168168
import { planThreadDeletion } from "./ThreadDeletion.ts";
169+
import { dispatchThreadIssueCommandFork } from "./ThreadIssues.fork.ts"; // fork-hook: github-issues/orchestrator-issues-import
169170
import { recordCheckoutRecoveryFork } from "./checkoutMove.fork.ts"; // fork-hook: zmux-estate/decider-recovery-record-import
170171
import {
171172
checkoutMoveMetadataFork,
@@ -501,6 +502,9 @@ function commandThreadId(command: OrchestrationV2ServerCommand): ThreadId {
501502
case "thread.pull-request.watch":
502503
case "thread.pull-request-watch.sync":
503504
case "thread.pull-request.sync":
505+
case "thread.issue.link": // fork-hook: github-issues/orchestrator-thread-id-link
506+
case "thread.issue.unlink": // fork-hook: github-issues/orchestrator-thread-id-unlink
507+
case "thread.issue-link.sync": // fork-hook: github-issues/orchestrator-thread-id-sync
504508
case "thread.title.regeneration.complete":
505509
case "thread.runtime-mode.set":
506510
case "thread.interaction-mode.set":
@@ -12583,6 +12587,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1258312587
case "thread.guest-message.dismiss":
1258412588
yield* dispatchGuestShare(command, events, effects);
1258512589
break;
12590+
case "thread.issue.link": // fork-hook: github-issues/orchestrator-dispatch-link
12591+
case "thread.issue.unlink": // fork-hook: github-issues/orchestrator-dispatch-unlink
12592+
case "thread.issue-link.sync": // fork-hook: github-issues/orchestrator-dispatch-sync
12593+
yield* dispatchThreadIssueCommandFork({
12594+
command,
12595+
getThread: projectionStore.getThread(command.threadId).pipe(mapDispatchError(command)),
12596+
emit: emit(events, command),
12597+
refuse: (cause) => mapDispatchError(command)(Effect.fail(cause)),
12598+
}); // fork-hook: github-issues/orchestrator-dispatch-call
12599+
break; // fork-hook: github-issues/orchestrator-dispatch-break
1258612600
case "provider-session.detach":
1258712601
yield* dispatchProviderSessionDetach(command, events, effects);
1258812602
break;

‎apps/server/src/orchestration-v2/ProjectionStore.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ import {
107107
THREAD_HISTORY_PAGE_POLICY,
108108
THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT,
109109
} from "./threadHistoryPaging.ts";
110+
import { threadIssuesField } from "./ThreadIssues.fork.ts"; // fork-hook: github-issues/projection-issues-import
110111
import { checkoutMoveShellFieldsFork } from "./checkoutMove.fork.ts"; // fork-hook: zmux-estate/shell-checkout-move-import
111112

112113
export class ProjectionStoreApplyEventError extends Schema.TaggedError<ProjectionStoreApplyEventError>()(
@@ -1658,6 +1659,7 @@ export function threadShellFromProjection(
16581659
worktreePath: projection.thread.worktreePath,
16591660
...checkoutMoveShellFieldsFork(projection.thread), // fork-hook: zmux-estate/shell-checkout-move
16601661
pullRequests: threadPullRequestsOf(projection.thread),
1662+
...threadIssuesField(projection.thread.issues), // fork-hook: github-issues/projection-thread-shell-issues
16611663
...(projection.thread.linkedPullRequest === undefined
16621664
? {}
16631665
: { linkedPullRequest: projection.thread.linkedPullRequest }),
@@ -1941,6 +1943,7 @@ function shellFromState(input: {
19411943
worktreePath: input.state.thread.worktreePath,
19421944
...checkoutMoveShellFieldsFork(input.state.thread), // fork-hook: zmux-estate/state-shell-checkout-move
19431945
pullRequests: threadPullRequestsOf(input.state.thread),
1946+
...threadIssuesField(input.state.thread.issues), // fork-hook: github-issues/projection-state-shell-issues
19441947
...(input.state.thread.linkedPullRequest === undefined
19451948
? {}
19461949
: { linkedPullRequest: input.state.thread.linkedPullRequest }),

0 commit comments

Comments
 (0)