@ripla/godd-mcp 1.0.4-canary.9 → 1.0.4

package/notes/app/src/lib/github-sync.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import {
+  GITHUB_SYNC_POLL_INTERVAL_MS,
+  hasIssueSnapshotChanged,
+  isIssueSnapshotStale,
+  shouldDispatchIssueListBackgroundSync,
+  shouldSyncGithub,
+} from "./github-sync";
+
+describe("github-sync", () => {
+  it("ポーリング間隔は 30 秒", () => {
+    expect(GITHUB_SYNC_POLL_INTERVAL_MS).toBe(30_000);
+  });
+
+  it("shouldSyncGithub は ready のみ true", () => {
+    expect(shouldSyncGithub("ready")).toBe(true);
+    expect(shouldSyncGithub("mock")).toBe(false);
+    expect(shouldSyncGithub("loading")).toBe(false);
+    expect(shouldSyncGithub("error")).toBe(false);
+  });
+
+  it("hasIssueSnapshotChanged は state / updatedAt / title / labels の差分を検知する", () => {
+    const base = {
+      state: "open" as const,
+      updatedAt: "2026-06-01T00:00:00Z",
+      title: "A",
+      labels: [{ name: "bug", color: "d73a4a" }],
+    };
+
+    expect(hasIssueSnapshotChanged(base, base)).toBe(false);
+    expect(hasIssueSnapshotChanged(base, { ...base, state: "closed" })).toBe(true);
+    expect(hasIssueSnapshotChanged(base, { ...base, updatedAt: "2026-06-02T00:00:00Z" })).toBe(true);
+    expect(hasIssueSnapshotChanged(base, { ...base, title: "B" })).toBe(true);
+    expect(
+      hasIssueSnapshotChanged(base, {
+        ...base,
+        labels: [{ name: "enhancement", color: "a2eeef" }],
+      }),
+    ).toBe(true);
+    expect(
+      hasIssueSnapshotChanged(base, {
+        ...base,
+        labels: [{ name: "bug", color: "ff0000" }],
+      }),
+    ).toBe(true);
+    expect(hasIssueSnapshotChanged(null, base)).toBe(false);
+  });
+
+  describe("isIssueSnapshotStale (#971)", () => {
+    const base = {
+      state: "open" as const,
+      updatedAt: "2026-06-10T00:00:00Z",
+      title: "A",
+      labels: [{ name: "bug", color: "d73a4a" }],
+    };
+
+    it("next の updatedAt が previous より古ければ stale（保存後の eventual consistency 読取）", () => {
+      expect(
+        isIssueSnapshotStale(base, { ...base, updatedAt: "2026-05-19T00:00:00Z" }),
+      ).toBe(true);
+    });
+
+    it("next の updatedAt が previous より新しければ stale ではない", () => {
+      expect(
+        isIssueSnapshotStale(base, { ...base, updatedAt: "2026-06-11T00:00:00Z" }),
+      ).toBe(false);
+    });
+
+    it("同一 updatedAt で snapshot 内容が後退する応答は stale（EC 同時刻 stale 読取・#979）", () => {
+      // GitHub の updated_at は編集ごとに前進するため、同一 updatedAt で内容が異なる応答は
+      // 正当な並行更新ではなく EC の古い replica 読取とみなす（巻き戻り防止）
+      expect(isIssueSnapshotStale(base, { ...base, title: "B" })).toBe(true);
+      expect(isIssueSnapshotStale(base, { ...base, state: "closed" })).toBe(true);
+      expect(
+        isIssueSnapshotStale(base, {
+          ...base,
+          labels: [{ name: "enhancement", color: "a2eeef" }],
+        }),
+      ).toBe(true);
+    });
+
+    it("同一 updatedAt でも snapshot 内容が同一なら stale ではない（適用は no-op）", () => {
+      expect(isIssueSnapshotStale(base, { ...base })).toBe(false);
+    });
+
+    it("同一インスタントを指す別フォーマットの updatedAt は内容判定で扱う（文字列差では stale にしない）", () => {
+      // 秒解像度で同一時刻だが文字列表現が異なる（Z / +00:00 / .000Z）応答。
+      // updatedAt 文字列の差ではなく snapshot 内容（state / title / labels）の差のみで stale を判定する
+      const equalInstant = [
+        "2026-06-10T00:00:00.000Z",
+        "2026-06-10T00:00:00+00:00",
+      ];
+      for (const updatedAt of equalInstant) {
+        // 内容同一: 文字列フォーマットが違っても stale 扱いしない（no-op）
+        expect(isIssueSnapshotStale(base, { ...base, updatedAt })).toBe(false);
+        // 内容後退: 同一インスタントなら別フォーマットでも stale
+        expect(isIssueSnapshotStale(base, { ...base, updatedAt, title: "B" })).toBe(true);
+      }
+    });
+
+    it("previous が無ければ stale ではない", () => {
+      expect(isIssueSnapshotStale(null, base)).toBe(false);
+    });
+
+    it("解析不能な日時は誤スキップを避けるため stale ではない", () => {
+      expect(isIssueSnapshotStale(base, { ...base, updatedAt: "invalid" })).toBe(false);
+      expect(
+        isIssueSnapshotStale({ ...base, updatedAt: "invalid" }, base),
+      ).toBe(false);
+    });
+  });
+
+  describe("shouldDispatchIssueListBackgroundSync (#932)", () => {
+    it("IssueList が periodic sync 中なら背景再取得を抑制する（重複回避）", () => {
+      expect(
+        shouldDispatchIssueListBackgroundSync({ issueListSyncing: true }),
+      ).toBe(false);
+    });
+
+    it("IssueList が periodic sync していなければ背景再取得を dispatch する（一覧を最新化）", () => {
+      expect(
+        shouldDispatchIssueListBackgroundSync({ issueListSyncing: false }),
+      ).toBe(true);
+    });
+  });
+});

package/notes/app/src/lib/github-sync.ts

@@ -0,0 +1,89 @@
+import type { IssueLabel, IssueSummary } from "@/lib/api";
+
+/** GitHub 上の変更を Notes UI に反映するポーリング間隔（ms） */
+export const GITHUB_SYNC_POLL_INTERVAL_MS = 30_000;
+
+export type IssueSnapshot = Pick<IssueSummary, "state" | "updatedAt" | "title" | "labels">;
+
+function issueLabelSignature(labels: IssueLabel[]): string {
+  return [...labels]
+    .map((label) => `${label.name}:${label.color}`)
+    .sort()
+    .join(",");
+}
+
+/**
+ * snapshot の内容（state / title / labels）が後退・変化したかを判定する（`updatedAt` は比較しない）。
+ * 同一インスタントの応答どうしを内容のみで比較したい同一秒 stale 判定（#979）で用いる。
+ */
+function hasIssueSnapshotContentChanged(
+  previous: IssueSnapshot,
+  next: IssueSnapshot,
+): boolean {
+  return (
+    previous.state !== next.state
+    || previous.title !== next.title
+    || issueLabelSignature(previous.labels) !== issueLabelSignature(next.labels)
+  );
+}
+
+export function hasIssueSnapshotChanged(
+  previous: IssueSnapshot | null | undefined,
+  next: IssueSnapshot,
+): boolean {
+  if (!previous) return false;
+  return previous.updatedAt !== next.updatedAt || hasIssueSnapshotContentChanged(previous, next);
+}
+
+/**
+ * `next`（poll / foreground load 応答）が現在表示中 `previous` に対して stale（巻き戻り）かを判定する
+ * （古い `updatedAt`: #971 / 同一秒の内容後退: #979）。
+ *
+ * GitHub の `updatedAt` は編集ごとに前進（単調増加）するため、次の応答は stale とみなせる:
+ * 1. `next.updatedAt` が `previous` より**古い**: 書込（save / close-reopen / label 変更）直後の
+ *    eventual consistency による更新前読取。
+ * 2. `next.updatedAt` が**同一秒**で snapshot 内容（state / title / labels）が異なる: 同一秒の古い
+ *    replica 読取（#979）。GitHub で同一 `updatedAt` が異なる正規スナップショットを指すことはないため、
+ *    内容が後退する同一秒応答は正当な並行更新ではなく EC の stale replica とみなす。
+ *
+ * いずれも適用・通知すると保存内容が一時的に巻き戻るため、呼び出し側はスキップする。現在表示を維持し、
+ * 厳密に新しい `updatedAt` の応答が届いた時点で通常どおり反映される（EC 解消後に自己回復）。
+ *
+ * 取得開始順の freshness ゲート（#949 / `appliedGen`）とは別軸（データの新しさ）で、save より後に
+ * 開始した取得はゲートを通過してしまうため本判定が必要。stale 応答では `appliedGen` を進めない
+ * （採用した取得のみ世代を消費する）。同一秒で内容が同一なら stale ではない（適用は no-op）。
+ * 本文（`body`）は snapshot 対象外のため、同一秒の body のみの差異は本判定の対象外（次 poll で反映）。
+ * いずれかが解析不能な日時なら誤スキップを避けるため `false` を返す。
+ */
+export function isIssueSnapshotStale(
+  previous: IssueSnapshot | null | undefined,
+  next: IssueSnapshot,
+): boolean {
+  if (!previous) return false;
+  const previousTime = Date.parse(previous.updatedAt);
+  const nextTime = Date.parse(next.updatedAt);
+  if (Number.isNaN(previousTime) || Number.isNaN(nextTime)) return false;
+  if (nextTime < previousTime) return true;
+  // 同一インスタント（updatedAt が同時刻）で snapshot 内容が後退する応答は EC の古い replica 読取（#979）。
+  // updatedAt は既に同時刻のため、文字列フォーマット差（Z / +00:00 等）に影響されない内容のみで判定する。
+  if (nextTime === previousTime) return hasIssueSnapshotContentChanged(previous, next);
+  return false;
+}
+
+export function shouldSyncGithub(apiState: "loading" | "ready" | "mock" | "error"): boolean {
+  return apiState === "ready";
+}
+
+/**
+ * 詳細 poll 起因の一覧背景再取得（IssueList の `backgroundSyncTrigger`）を dispatch すべきか判定する（#932）。
+ *
+ * IssueList が自前の periodic sync 中（Issues タブ表示 + live）は、毎周期で一覧全体（選択中 Issue 含む）を
+ * 背景再取得している。そこへ詳細 poll の変更検知でさらに再取得を重ねると同一周期内に
+ * `GET /api/issues` が二重 dispatch されるため抑制する。
+ * タブ非表示などで IssueList が同期していない場合は、（隠れた）一覧を最新に保つため dispatch する。
+ */
+export function shouldDispatchIssueListBackgroundSync(params: {
+  issueListSyncing: boolean;
+}): boolean {
+  return !params.issueListSyncing;
+}

package/notes/app/src/lib/issue-list-utils.test.ts

@@ -0,0 +1,275 @@
+import { describe, it, expect } from "vitest";
+import {
+  issueMatchesListFilter,
+  mergeOptimisticIssue,
+  isValidAssigneeFilter,
+  issueDetailToSummary,
+  isOptimisticIssueSettled,
+  shouldClearOptimisticForSelection,
+} from "./issue-list-utils";
+import type { IssueDetail, IssueSummary } from "@/lib/api";
+
+const baseIssue = (overrides: Partial<IssueSummary> = {}): IssueSummary => ({
+  number: 1,
+  title: "Test",
+  state: "open",
+  labels: [],
+  author: "user",
+  assignees: [],
+  comments: 0,
+  createdAt: "2026-05-25T00:00:00Z",
+  updatedAt: "2026-05-25T00:00:00Z",
+  ...overrides,
+});
+
+const baseDetail = (overrides: Partial<IssueDetail> = {}): IssueDetail => ({
+  ...baseIssue(),
+  body: "本文",
+  url: "https://github.com/ripla-inc/GoDD/issues/1",
+  ...overrides,
+});
+
+describe("issueMatchesListFilter", () => {
+  it("open フィルタで open Issue のみ一致する", () => {
+    expect(issueMatchesListFilter(baseIssue({ state: "open" }), "open", "", "")).toBe(true);
+    expect(issueMatchesListFilter(baseIssue({ state: "closed" }), "open", "", "")).toBe(false);
+  });
+
+  it("ラベルフィルタが設定されている場合は該当ラベルを持つ Issue のみ一致する", () => {
+    const labeled = baseIssue({ labels: [{ name: "bug", color: "d73a4a" }] });
+    expect(issueMatchesListFilter(labeled, "open", "bug", "")).toBe(true);
+    expect(issueMatchesListFilter(labeled, "open", "enhancement", "")).toBe(false);
+  });
+
+  it("担当者 none フィルタでは未割当 Issue のみ一致する", () => {
+    expect(issueMatchesListFilter(baseIssue({ assignees: [] }), "open", "", "none")).toBe(true);
+    expect(
+      issueMatchesListFilter(baseIssue({ assignees: ["octocat"] }), "open", "", "none"),
+    ).toBe(false);
+  });
+
+  it("担当者フィルタでは指定ユーザーが assignees に含まれる Issue のみ一致する", () => {
+    const assigned = baseIssue({ assignees: ["octocat"] });
+    expect(issueMatchesListFilter(assigned, "open", "", "octocat")).toBe(true);
+    expect(issueMatchesListFilter(assigned, "open", "", "hubot")).toBe(false);
+  });
+});
+
+describe("isValidAssigneeFilter", () => {
+  it("空文字・none・有効な GitHub login を許可する", () => {
+    expect(isValidAssigneeFilter("")).toBe(true);
+    expect(isValidAssigneeFilter("none")).toBe(true);
+    expect(isValidAssigneeFilter("octocat")).toBe(true);
+  });
+
+  it("不正な入力を拒否する", () => {
+    expect(isValidAssigneeFilter("-invalid")).toBe(false);
+    expect(isValidAssigneeFilter("user-")).toBe(false);
+    expect(isValidAssigneeFilter("has space")).toBe(false);
+  });
+});
+
+describe("mergeOptimisticIssue", () => {
+  const existing = [
+    baseIssue({ number: 10, title: "Issue 10" }),
+    baseIssue({ number: 9, title: "Issue 9" }),
+  ];
+
+  it("optimistic Issue を先頭付近にマージし、重複を除去する", () => {
+    const optimistic = baseIssue({ number: 11, title: "New Issue" });
+    const merged = mergeOptimisticIssue(existing, optimistic, "open", "", "");
+
+    expect(merged.map((issue) => issue.number)).toEqual([11, 10, 9]);
+  });
+
+  it("フィルタ条件に合わない optimistic Issue はマージしない", () => {
+    const optimistic = baseIssue({ number: 11, state: "closed" });
+    const merged = mergeOptimisticIssue(existing, optimistic, "open", "", "");
+
+    expect(merged).toEqual(existing);
+  });
+
+  it("API 取得結果に同じ番号が含まれる場合は optimistic を置き換える", () => {
+    const optimistic = baseIssue({ number: 10, title: "Optimistic title" });
+    const merged = mergeOptimisticIssue(existing, optimistic, "open", "", "");
+
+    expect(merged.filter((issue) => issue.number === 10)).toHaveLength(1);
+    expect(merged[0]?.title).toBe("Optimistic title");
+  });
+
+  it("一覧内の Issue がフィルタ非一致になった optimistic は即時に除外する（#945）", () => {
+    // open フィルタ中に選択 Issue #10 が closed 化したケース
+    const optimistic = baseIssue({ number: 10, state: "closed" });
+    const merged = mergeOptimisticIssue(existing, optimistic, "open", "", "");
+
+    expect(merged.map((issue) => issue.number)).toEqual([9]);
+  });
+
+  it("除外対象が無いフィルタ非一致では元配列の参照を維持する（#945）", () => {
+    // #11 closed は一覧に存在しないため、何も除外せず参照を保つ
+    const optimistic = baseIssue({ number: 11, state: "closed" });
+    const merged = mergeOptimisticIssue(existing, optimistic, "open", "", "");
+
+    expect(merged).toBe(existing);
+  });
+});
+
+describe("issueDetailToSummary", () => {
+  it("IssueDetail から body / url を落として IssueSummary を射影する（#945）", () => {
+    const detail = baseDetail({
+      number: 42,
+      title: "Detail title",
+      state: "closed",
+      labels: [{ name: "bug", color: "d73a4a" }],
+      assignees: ["octocat"],
+      comments: 3,
+      updatedAt: "2026-06-10T00:00:00Z",
+    });
+
+    const summary = issueDetailToSummary(detail);
+
+    expect(summary).toEqual({
+      number: 42,
+      title: "Detail title",
+      state: "closed",
+      labels: [{ name: "bug", color: "d73a4a" }],
+      author: "user",
+      assignees: ["octocat"],
+      comments: 3,
+      createdAt: "2026-05-25T00:00:00Z",
+      updatedAt: "2026-06-10T00:00:00Z",
+    });
+    expect("body" in summary).toBe(false);
+    expect("url" in summary).toBe(false);
+  });
+});
+
+describe("isOptimisticIssueSettled", () => {
+  const listIssues = [
+    baseIssue({ number: 10, updatedAt: "2026-05-19T00:00:00Z" }),
+    baseIssue({ number: 9, updatedAt: "2026-05-18T00:00:00Z" }),
+  ];
+
+  describe("presence モード（新規作成）", () => {
+    it("同番号が一覧に出現したら解除する（実体が optimistic より古くても可）", () => {
+      const optimistic = baseIssue({ number: 10, updatedAt: "2026-05-25T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, listIssues, "presence", "open", "", ""),
+      ).toBe(true);
+    });
+
+    it("同番号が一覧に無ければ解除しない", () => {
+      const optimistic = baseIssue({ number: 11 });
+      expect(
+        isOptimisticIssueSettled(optimistic, listIssues, "presence", "open", "", ""),
+      ).toBe(false);
+    });
+  });
+
+  describe("snapshot モード（外部変更の即時反映）", () => {
+    it("一覧側がまだ古い間は解除しない（先に解除すると表示が巻き戻る）", () => {
+      const optimistic = baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, listIssues, "snapshot", "open", "", ""),
+      ).toBe(false);
+    });
+
+    it("一覧側の実体が optimistic に追いついたら解除する", () => {
+      const caughtUp = [
+        baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" }),
+        baseIssue({ number: 9 }),
+      ];
+      const optimistic = baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, caughtUp, "snapshot", "open", "", ""),
+      ).toBe(true);
+    });
+
+    it("一覧が確実に新しい（後続変更で追い越し）なら内容差分があっても解除する", () => {
+      // optimistic より後の別変更で一覧が updatedAt を追い越したケース（一覧を信頼）
+      const overtaken = [
+        baseIssue({ number: 10, title: "後続変更", updatedAt: "2026-06-11T00:00:00Z" }),
+      ];
+      const optimistic = baseIssue({ number: 10, title: "古い optimistic", updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, overtaken, "snapshot", "open", "", ""),
+      ).toBe(true);
+    });
+
+    it("同時刻でも一覧行が stale 内容なら解除しない（早期解除での巻き戻り防止）", () => {
+      // updatedAt は秒解像度。タイムスタンプ一致でも内容（title）が未追従なら待機する
+      const sameTimeStale = [
+        baseIssue({ number: 10, title: "stale", updatedAt: "2026-06-10T00:00:00Z" }),
+      ];
+      const optimistic = baseIssue({ number: 10, title: "更新済み", updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, sameTimeStale, "snapshot", "open", "", ""),
+      ).toBe(false);
+    });
+
+    it("フィルタ非一致で一覧から除外された場合は解除する（open フィルタ中の closed 化）", () => {
+      // 再取得で #10 が open 一覧から消えた状態
+      const withoutClosed = [baseIssue({ number: 9 })];
+      const optimistic = baseIssue({ number: 10, state: "closed", updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, withoutClosed, "snapshot", "open", "", ""),
+      ).toBe(true);
+    });
+
+    it("フィルタには一致するのに未取得（ページ範囲外など）なら解除しない", () => {
+      const withoutTen = [baseIssue({ number: 9 })];
+      const optimistic = baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, withoutTen, "snapshot", "open", "", ""),
+      ).toBe(false);
+    });
+
+    it("updatedAt が空文字・不正で比較不能なら実体を信頼して解除する（#945）", () => {
+      // バックエンドが updated_at 未取得時に "" を返すケース（NaN 比較で固着させない）
+      const listWithEmpty = [baseIssue({ number: 10, updatedAt: "" })];
+      const optimistic = baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" });
+      expect(
+        isOptimisticIssueSettled(optimistic, listWithEmpty, "snapshot", "open", "", ""),
+      ).toBe(true);
+
+      const optimisticEmpty = baseIssue({ number: 10, updatedAt: "" });
+      expect(
+        isOptimisticIssueSettled(
+          optimisticEmpty,
+          [baseIssue({ number: 10, updatedAt: "2026-06-10T00:00:00Z" })],
+          "snapshot",
+          "open",
+          "",
+          "",
+        ),
+      ).toBe(true);
+    });
+  });
+});
+
+describe("shouldClearOptimisticForSelection", () => {
+  it("snapshot optimistic は選択中 Issue から離れたら破棄する（#945）", () => {
+    const optimistic = baseIssue({ number: 10 });
+    // 別 Issue へ移動
+    expect(shouldClearOptimisticForSelection(optimistic, "snapshot", 11)).toBe(true);
+    // "new" へ移動
+    expect(shouldClearOptimisticForSelection(optimistic, "snapshot", "new")).toBe(true);
+    // 未選択へ
+    expect(shouldClearOptimisticForSelection(optimistic, "snapshot", null)).toBe(true);
+  });
+
+  it("選択中 Issue が optimistic と一致する間は破棄しない", () => {
+    const optimistic = baseIssue({ number: 10 });
+    expect(shouldClearOptimisticForSelection(optimistic, "snapshot", 10)).toBe(false);
+  });
+
+  it("presence（新規作成）は選択変化で破棄しない（番号出現で解除する）", () => {
+    const optimistic = baseIssue({ number: 10 });
+    expect(shouldClearOptimisticForSelection(optimistic, "presence", 11)).toBe(false);
+    expect(shouldClearOptimisticForSelection(optimistic, "presence", null)).toBe(false);
+  });
+
+  it("optimistic が無ければ破棄不要", () => {
+    expect(shouldClearOptimisticForSelection(null, "snapshot", 11)).toBe(false);
+  });
+});

package/notes/app/src/lib/issue-list-utils.ts

@@ -0,0 +1,135 @@
+import type { IssueDetail, IssueSummary } from "@/lib/api";
+import { hasIssueSnapshotChanged } from "@/lib/github-sync";
+
+const GITHUB_LOGIN_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/;
+
+/**
+ * optimistic スロットの解除（`onOptimisticSettled`）判定方式（#945）。
+ *
+ * - `presence`: 一覧に同番号 Issue が現れた時点で解除（新規作成の eventual consistency 対策。#932）。
+ *   実体取得が optimistic より古くても「番号が出現したら確定」とみなす。
+ * - `snapshot`: 一覧側の実体が optimistic と同等以上に新しくなった時点で解除（選択中 Issue の外部変更を
+ *   即時反映するケース。詳細 poll が取得済みの新スナップショットを渡すため、古い一覧行で先に解除すると
+ *   表示が巻き戻る）。フィルタ非一致で一覧から除外された場合も「反映済み」とみなして解除する。
+ */
+export type OptimisticSettleMode = "presence" | "snapshot";
+
+export function isValidAssigneeFilter(value: string): boolean {
+  if (!value) return true;
+  if (value === "none") return true;
+  return GITHUB_LOGIN_RE.test(value);
+}
+
+export function issueMatchesListFilter(
+  issue: IssueSummary,
+  stateFilter: "open" | "closed",
+  labelFilter: string,
+  assigneeFilter: string,
+): boolean {
+  if (issue.state !== stateFilter) return false;
+  if (labelFilter && !issue.labels.some((label) => label.name === labelFilter)) {
+    return false;
+  }
+  if (assigneeFilter === "none") {
+    if (issue.assignees.length > 0) return false;
+  } else if (assigneeFilter && !issue.assignees.includes(assigneeFilter)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 詳細ビューの `IssueDetail` を一覧行用の `IssueSummary` へ射影する（#945）。
+ * `body` / `url` を落とし、optimistic スロットに余分なフィールドを持ち込まない。
+ */
+export function issueDetailToSummary(detail: IssueDetail): IssueSummary {
+  return {
+    number: detail.number,
+    title: detail.title,
+    state: detail.state,
+    labels: detail.labels,
+    author: detail.author,
+    assignees: detail.assignees,
+    comments: detail.comments,
+    createdAt: detail.createdAt,
+    updatedAt: detail.updatedAt,
+  };
+}
+
+export function mergeOptimisticIssue(
+  issues: IssueSummary[],
+  optimisticIssue: IssueSummary | null | undefined,
+  stateFilter: "open" | "closed",
+  labelFilter: string,
+  assigneeFilter: string,
+): IssueSummary[] {
+  if (!optimisticIssue) return issues;
+
+  const withoutDuplicate = issues.filter((issue) => issue.number !== optimisticIssue.number);
+
+  if (!issueMatchesListFilter(optimisticIssue, stateFilter, labelFilter, assigneeFilter)) {
+    // 最新スナップショットが現在のフィルタに非一致（例: open フィルタ中に選択 Issue が closed 化、
+    // ラベルが外れる）なら、一覧から即時に除外する。除外対象が無ければ参照を維持して再描画を避ける。
+    return withoutDuplicate.length === issues.length ? issues : withoutDuplicate;
+  }
+
+  return [optimisticIssue, ...withoutDuplicate].sort((a, b) => b.number - a.number);
+}
+
+/**
+ * optimistic スロットを解除してよいか（実体が反映されたか）を判定する（#945）。
+ *
+ * @param mode 解除方式。`presence` は同番号の出現で解除、`snapshot` は実体が optimistic と
+ *   同等以上に新しくなった（または現在のフィルタから除外された）時点で解除する。
+ */
+export function isOptimisticIssueSettled(
+  optimisticIssue: IssueSummary,
+  issues: IssueSummary[],
+  mode: OptimisticSettleMode,
+  stateFilter: "open" | "closed",
+  labelFilter: string,
+  assigneeFilter: string,
+): boolean {
+  const match = issues.find((issue) => issue.number === optimisticIssue.number);
+
+  if (mode === "presence") {
+    return match !== undefined;
+  }
+
+  // snapshot: 一覧側の実体が optimistic に追いついたら解除する
+  if (match) {
+    const listTime = Date.parse(match.updatedAt);
+    const optimisticTime = Date.parse(optimisticIssue.updatedAt);
+    // updatedAt が空文字・不正値（バックエンドは未取得時に "" を返しうる）で比較不能なら、
+    // 一覧（実体）を信頼して解除する。比較不能を理由に optimistic を固定し続けない。
+    if (Number.isNaN(listTime) || Number.isNaN(optimisticTime)) return true;
+    // 一覧が確実に新しい（別の後続変更で追い越した場合を含む）なら解除する。
+    if (listTime > optimisticTime) return true;
+    // 同時刻（updatedAt は秒解像度）の場合は、内容が optimistic に追いついた時のみ解除する。
+    // タイムスタンプ一致でも一覧行がまだ stale 内容なら、早期解除で表示が巻き戻るのを防ぐ。
+    return listTime === optimisticTime && !hasIssueSnapshotChanged(optimisticIssue, match);
+  }
+
+  // 一覧に存在しない場合、フィルタ非一致で正当に除外されていれば「反映済み」として解除する。
+  // フィルタには一致するのに未取得（ページ範囲外など）なら、表示継続のため解除しない。
+  return !issueMatchesListFilter(optimisticIssue, stateFilter, labelFilter, assigneeFilter);
+}
+
+/**
+ * 選択中 Issue の変化に伴って snapshot optimistic を破棄すべきか判定する（#945）。
+ *
+ * snapshot optimistic は「選択中 Issue の詳細 poll が検知した外部変更」を一覧行へ橋渡しするための
+ * 一時状態。別 Issue（または `"new"` / 未選択）へ移動した時点で対象外となるため破棄し、古い行は
+ * `IssueList` 自前の periodic sync に委ねる。`presence`（新規作成）は対象外で、従来どおり番号出現で解除する。
+ */
+export function shouldClearOptimisticForSelection(
+  optimisticIssue: IssueSummary | null,
+  mode: OptimisticSettleMode,
+  selectedIssue: number | "new" | null,
+): boolean {
+  return (
+    optimisticIssue !== null
+    && mode === "snapshot"
+    && optimisticIssue.number !== selectedIssue
+  );
+}

package/notes/app/src/lib/issue-mobile-layout.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import {
+  ISSUE_MOBILE_ACTION_BUTTON,
+  ISSUE_MOBILE_DETAIL_ROOT,
+  ISSUE_MOBILE_LIST_ITEM,
+  ISSUE_MOBILE_TAP_TARGET,
+} from "./issue-mobile-layout";
+
+describe("issue-mobile-layout", () => {
+  it("モバイル向けタップ領域クラスを含む", () => {
+    expect(ISSUE_MOBILE_TAP_TARGET).toContain("min-h-11");
+    expect(ISSUE_MOBILE_TAP_TARGET).toContain("touch-manipulation");
+    expect(ISSUE_MOBILE_LIST_ITEM).toContain("min-h-11");
+    expect(ISSUE_MOBILE_ACTION_BUTTON).toContain("w-full sm:w-auto");
+    expect(ISSUE_MOBILE_DETAIL_ROOT).toContain("overflow-y-auto");
+  });
+});

package/notes/app/src/lib/issue-mobile-layout.ts

@@ -0,0 +1,20 @@
+/** Shared Tailwind classes for Issue panel mobile UX (< md / 768px). */
+export const ISSUE_MOBILE_TAP_TARGET =
+  "min-h-11 touch-manipulation sm:min-h-0 sm:touch-auto";
+
+export const ISSUE_MOBILE_FILTER_CONTROL =
+  "min-h-10 touch-manipulation sm:min-h-0 sm:touch-auto";
+
+export const ISSUE_MOBILE_LIST_ITEM =
+  "min-h-11 py-2.5 touch-manipulation sm:min-h-0 sm:py-1.5";
+
+export const ISSUE_MOBILE_ACTION_ROW =
+  "flex flex-col sm:flex-row items-stretch sm:items-center gap-2";
+
+export const ISSUE_MOBILE_ACTION_BUTTON = [
+  ISSUE_MOBILE_TAP_TARGET,
+  "w-full sm:w-auto px-4 py-2.5 sm:px-3 sm:py-1 rounded text-sm",
+].join(" ");
+
+export const ISSUE_MOBILE_DETAIL_ROOT =
+  "flex flex-col min-h-0 h-full overflow-y-auto overscroll-y-contain p-3 sm:p-6 max-w-3xl mx-auto w-full";