From 30dea9feae0d6435f2d7ec0831b426fe8a0f85fc Mon Sep 17 00:00:00 2001
From: elkaix <melkholy@techmatrix.com>
Date: Sun, 16 Aug 2026 05:11:59 -0400
Subject: [PATCH 1/4] feat(question): keep questions open until answered and
 return labels

Questions no longer expire after 60 seconds. An expired lease is no longer
reported as a user dismissal, answers carry the question text and the option
labels the user saw, and Escape no longer dismisses an open question.
---
 .changeset/question-lease-and-labels.md       |   5 +
 apps/pythinker-web/AGENTS.md                  |   8 +-
 .../src/components/QuestionCard.vue           |  41 +++++--
 .../src/composables/usePythinkerWebClient.ts  |   1 +
 .../src/i18n/locales/en/question.ts           |   2 +
 apps/pythinker-web/src/types.ts               |   1 +
 .../test/question-card-lifecycle.test.ts      | 115 ++++++++++++++++++
 .../test/question-card-recommended.test.ts    |   1 +
 packages/agent-core/src/errors/codes.ts       |   7 ++
 .../src/services/question/question.ts         |  63 +++++-----
 .../tools/builtin/collaboration/ask-user.ts   |  20 ++-
 .../test/services/question-adapter.test.ts    | 102 ++++++++++------
 .../agent-core/test/tools/ask-user.test.ts    |  34 ++++--
 packages/protocol/src/events.ts               |   1 +
 packages/server/src/routes/questions.ts       |  15 ++-
 .../src/services/question/questionService.ts  |  31 +++--
 packages/server/test/question.e2e.test.ts     |  51 ++++++--
 packages/server/test/services.test.ts         |   5 +-
 18 files changed, 386 insertions(+), 117 deletions(-)
 create mode 100644 .changeset/question-lease-and-labels.md
 create mode 100644 apps/pythinker-web/test/question-card-lifecycle.test.ts

diff --git a/.changeset/question-lease-and-labels.md b/.changeset/question-lease-and-labels.md
new file mode 100644
index 00000000..a5dd49e0
--- /dev/null
+++ b/.changeset/question-lease-and-labels.md
@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-code': patch
+---
+
+Questions no longer expire after 60 seconds, expired questions are not reported as user dismissals, answers retain question text and option labels, and Escape no longer dismisses a question.
diff --git a/apps/pythinker-web/AGENTS.md b/apps/pythinker-web/AGENTS.md
index 2f7e0784..7206cfba 100644
--- a/apps/pythinker-web/AGENTS.md
+++ b/apps/pythinker-web/AGENTS.md
@@ -23,13 +23,13 @@ The browser web UI for Pythinker Code — a peer to the TUI in `apps/pythinker-c
 - Shared components go in `src/components/`; reusable logic goes in `src/composables/` with a `use` prefix.
 - There is **no auto-import plugin** and **no path alias** — `#/` and `@/` are intentionally unused. Write relative imports (`../i18n`, `./config`).
 
-## i18n (normative — keeping locales in sync is manual)
+## i18n (normative — the app is English-only)
 
 - Setup: `src/i18n/index.ts`, vue-i18n in Composition mode (`legacy: false`), fallback `en`. The active locale is persisted in `localStorage` under `pythinker-locale`.
-- Locale files: `src/i18n/locales/{en,zh}/<namespace>.ts`, each `export default { ... } as const`. New namespaces are registered in `src/i18n/locales/index.ts`.
+- **`en` is the only locale.** `src/i18n/locales/` contains exactly one directory, and `locales/index.ts` registers only `en`. Do not add a second locale, and do not "restore parity" with one that does not exist.
+- Locale files: `src/i18n/locales/en/<namespace>.ts`, each `export default { ... } as const`. New namespaces are registered in `src/i18n/locales/index.ts`.
 - Reference with `const { t } = useI18n()` and `t('namespace.key')` (same form in templates).
-- **Adding a key:** add it to **both** `en/<ns>.ts` and `zh/<ns>.ts`. **Adding a namespace:** create the file in both locales **and** register it in `locales/index.ts`.
-- There is **no automated missing-key or en/zh parity check**. Keeping the two locales in sync is a manual responsibility — do not leave a key present in only one locale.
+- **Adding a key:** add it to `en/<ns>.ts`. **Adding a namespace:** create the file under `en/` **and** register it in `locales/index.ts`.
 
 ## Commands
 
diff --git a/apps/pythinker-web/src/components/QuestionCard.vue b/apps/pythinker-web/src/components/QuestionCard.vue
index 829b4aeb..06eea682 100644
--- a/apps/pythinker-web/src/components/QuestionCard.vue
+++ b/apps/pythinker-web/src/components/QuestionCard.vue
@@ -30,6 +30,22 @@ const total = computed(() => props.question.questions.length);
 const hasPreview = computed(() =>
   current.value.options.some((option) => option.preview?.trim()),
 );
+const now = ref(Date.now());
+const remainingMinutes = computed(() => {
+  const expiresAt = Date.parse(props.question.expiresAt);
+  if (Number.isNaN(expiresAt)) return undefined;
+  return Math.ceil((expiresAt - now.value) / 60_000);
+});
+const leaseWarning = computed(() => {
+  const expiresAt = Date.parse(props.question.expiresAt);
+  if (Number.isNaN(expiresAt)) return undefined;
+  const remainingMs = expiresAt - now.value;
+  if (remainingMs <= 0 || remainingMs >= 5 * 60_000) return undefined;
+  if (remainingMs < 60_000) return t('question.expiresSoonSeconds');
+  const minutes = remainingMinutes.value;
+  if (minutes === undefined) return undefined;
+  return t('question.expiresSoon', { minutes });
+});
 
 function goBack(): void {
   if (step.value > 0) step.value--;
@@ -207,17 +223,15 @@ function dismiss(): void {
 }
 
 // ---------------------------------------------------------------------------
-// Keyboard: number keys pick options for current question, Enter submit, Esc dismiss
+// Keyboard: number keys pick options for the current question and Enter submits.
 // ---------------------------------------------------------------------------
 
 function handleKeydown(e: KeyboardEvent): void {
   const tag = (document.activeElement?.tagName ?? '').toLowerCase();
   if (tag === 'input' || tag === 'textarea') return;
-  // While minimized the options aren't visible, so don't let number keys pick
-  // an unseen answer; only Escape (dismiss) stays live.
-  if (minimized.value && e.key !== 'Escape') return;
+  // While minimized the options are not visible, so keyboard selection is disabled.
+  if (minimized.value) return;
 
-  if (e.key === 'Escape') { e.preventDefault(); dismiss(); return; }
   if (e.key === 'Enter') { e.preventDefault(); submit(); return; }
 
   const num = parseInt(e.key, 10);
@@ -236,8 +250,19 @@ function handleKeydown(e: KeyboardEvent): void {
   }
 }
 
-onMounted(() => document.addEventListener('keydown', handleKeydown));
-onUnmounted(() => document.removeEventListener('keydown', handleKeydown));
+let leaseTimer: ReturnType<typeof setInterval> | undefined;
+
+onMounted(() => {
+  document.addEventListener('keydown', handleKeydown);
+  leaseTimer = setInterval(() => {
+    now.value = Date.now();
+  }, 30_000);
+});
+
+onUnmounted(() => {
+  document.removeEventListener('keydown', handleKeydown);
+  if (leaseTimer !== undefined) clearInterval(leaseTimer);
+});
 </script>
 
 <template>
@@ -245,6 +270,7 @@ onUnmounted(() => document.removeEventListener('keydown', handleKeydown));
     <!-- Step indicator (multi-question) -->
     <div class="qh">
       <span class="qtitle">{{ t('question.title') }}</span>
+      <span v-if="leaseWarning" class="qexpires">{{ leaseWarning }}</span>
       <template v-if="total > 1 && !minimized">
         <span class="qstep">{{ t('question.step', { current: step + 1, total }) }}</span>
         <button class="qnav" :disabled="step === 0" @click="goBack">{{ t('question.prev') }}</button>
@@ -371,6 +397,7 @@ onUnmounted(() => document.removeEventListener('keydown', handleKeydown));
 }
 .qtitle { color: var(--blue2); font-weight: 700; }
 .qstep { color: var(--muted); font-size: calc(var(--ui-font-size) - 3px); margin-left: 4px; }
+.qexpires { color: var(--muted); font-size: calc(var(--ui-font-size) - 3px); margin-left: 4px; }
 .qnav {
   font-family: var(--mono);
   font-size: calc(var(--ui-font-size) - 3px);
diff --git a/apps/pythinker-web/src/composables/usePythinkerWebClient.ts b/apps/pythinker-web/src/composables/usePythinkerWebClient.ts
index 0f4c65c4..295848a3 100644
--- a/apps/pythinker-web/src/composables/usePythinkerWebClient.ts
+++ b/apps/pythinker-web/src/composables/usePythinkerWebClient.ts
@@ -1660,6 +1660,7 @@ function toUiQuestion(q: AppQuestionRequest): UIQuestion {
   return {
     questionId: q.questionId,
     sessionId: q.sessionId,
+    expiresAt: q.expiresAt,
     questions: q.questions.map((qi) => ({
       id: qi.id,
       question: qi.question,
diff --git a/apps/pythinker-web/src/i18n/locales/en/question.ts b/apps/pythinker-web/src/i18n/locales/en/question.ts
index af18e71a..8755ff26 100644
--- a/apps/pythinker-web/src/i18n/locales/en/question.ts
+++ b/apps/pythinker-web/src/i18n/locales/en/question.ts
@@ -10,4 +10,6 @@ export default {
   dismiss: 'Dismiss',
   minimize: 'Minimize',
   expand: 'Expand',
+  expiresSoon: 'Expires in {minutes} min',
+  expiresSoonSeconds: 'Expires in less than a minute',
 } as const;
diff --git a/apps/pythinker-web/src/types.ts b/apps/pythinker-web/src/types.ts
index 0b829e45..1022f350 100644
--- a/apps/pythinker-web/src/types.ts
+++ b/apps/pythinker-web/src/types.ts
@@ -242,6 +242,7 @@ export interface QueuedPromptView {
 export interface UIQuestion {
   questionId: string;
   sessionId: string;
+  expiresAt: string;
   questions: {
     id: string;
     question: string;
diff --git a/apps/pythinker-web/test/question-card-lifecycle.test.ts b/apps/pythinker-web/test/question-card-lifecycle.test.ts
new file mode 100644
index 00000000..7432fe0e
--- /dev/null
+++ b/apps/pythinker-web/test/question-card-lifecycle.test.ts
@@ -0,0 +1,115 @@
+import { mount } from '@vue/test-utils';
+import { createI18n } from 'vue-i18n';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import QuestionCard from '../src/components/QuestionCard.vue';
+import type { UIQuestion } from '../src/types';
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      question: {
+        title: 'Question',
+        step: '{current}/{total}',
+        prev: 'Prev',
+        next: 'Next',
+        expand: 'Expand',
+        minimize: 'Minimize',
+        otherDefault: 'Other',
+        submit: 'Submit',
+        dismiss: 'Dismiss',
+        notes: 'Notes',
+        notesPlaceholder: 'Add notes on this option',
+        expiresSoon: 'Expires in {minutes} min',
+        expiresSoonSeconds: 'Expires in less than a minute',
+      },
+    },
+  },
+  missingWarn: false,
+  fallbackWarn: false,
+});
+
+const mounted: ReturnType<typeof mount>[] = [];
+
+function question(expiresAt: string): UIQuestion {
+  return {
+    questionId: 'qreq_1',
+    sessionId: 'sess_1',
+    expiresAt,
+    questions: [
+      {
+        id: 'q1',
+        question: 'Pick one',
+        options: [
+          { id: 'a', label: 'A' },
+          { id: 'b', label: 'B' },
+        ],
+      },
+    ],
+  };
+}
+
+function mountCard(input: UIQuestion) {
+  const wrapper = mount(QuestionCard, {
+    props: { question: input },
+    global: {
+      plugins: [i18n],
+      stubs: {
+        Markdown: {
+          props: ['text'],
+          template: '<pre class="markdown-stub">{{ text }}</pre>',
+        },
+      },
+    },
+  });
+  mounted.push(wrapper);
+  return wrapper;
+}
+
+afterEach(() => {
+  for (const wrapper of mounted.splice(0)) wrapper.unmount();
+});
+
+describe('QuestionCard lifecycle', () => {
+  it('does not dismiss when Escape is pressed', () => {
+    const wrapper = mountCard(question(new Date(Date.now() + 20 * 60_000).toISOString()));
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+
+    expect(wrapper.emitted('dismiss')).toBeUndefined();
+  });
+
+  it('shows an expiry warning within five minutes and hides it at twenty minutes', () => {
+    const soon = mountCard(question(new Date(Date.now() + 2 * 60_000).toISOString()));
+    const later = mountCard(question(new Date(Date.now() + 20 * 60_000).toISOString()));
+
+    expect(soon.find('.qexpires').text()).toBe('Expires in 2 min');
+    expect(later.find('.qexpires').exists()).toBe(false);
+  });
+
+  it('hides the expiry warning at five minutes and shows it at four minutes fifty-nine seconds', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+    try {
+      const boundary = mountCard(question(new Date(Date.now() + 5 * 60_000).toISOString()));
+      const soon = mountCard(question(new Date(Date.now() + 4 * 60_000 + 59_000).toISOString()));
+
+      expect(boundary.find('.qexpires').exists()).toBe(false);
+      expect(soon.find('.qexpires').exists()).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('ignores Enter while minimized', async () => {
+    const wrapper = mountCard(question(new Date(Date.now() + 20 * 60_000).toISOString()));
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: '1', bubbles: true }));
+    await wrapper.find('.qmin').trigger('click');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    expect(wrapper.emitted('answer')).toBeUndefined();
+  });
+});
diff --git a/apps/pythinker-web/test/question-card-recommended.test.ts b/apps/pythinker-web/test/question-card-recommended.test.ts
index d1455478..26f28bf1 100644
--- a/apps/pythinker-web/test/question-card-recommended.test.ts
+++ b/apps/pythinker-web/test/question-card-recommended.test.ts
@@ -35,6 +35,7 @@ function question(overrides: Partial<UIQuestion['questions'][number]> = {}): UIQ
   return {
     questionId: 'qreq_1',
     sessionId: 'sess_1',
+    expiresAt: new Date(Date.now() + 20 * 60_000).toISOString(),
     questions: [
       {
         id: 'q1',
diff --git a/packages/agent-core/src/errors/codes.ts b/packages/agent-core/src/errors/codes.ts
index b9e5ffc7..e0563ad1 100644
--- a/packages/agent-core/src/errors/codes.ts
+++ b/packages/agent-core/src/errors/codes.ts
@@ -33,6 +33,7 @@ export const ErrorCodes = {
 
   AGENT_NOT_FOUND: 'agent.not_found',
   TURN_AGENT_BUSY: 'turn.agent_busy',
+  QUESTION_EXPIRED: 'question.expired',
 
   GOAL_ALREADY_EXISTS: 'goal.already_exists',
   GOAL_NOT_FOUND: 'goal.not_found',
@@ -229,6 +230,12 @@ export const PYTHINKER_ERROR_INFO = {
     public: true,
     action: 'Wait for the current turn to finish or steer it.',
   },
+  'question.expired': {
+    title: 'Question expired',
+    retryable: false,
+    public: true,
+    action: 'Ask the user again if you still need the answer.',
+  },
 
   'goal.already_exists': {
     title: 'A goal is already active',
diff --git a/packages/agent-core/src/services/question/question.ts b/packages/agent-core/src/services/question/question.ts
index 5c7a11a0..96ea3173 100644
--- a/packages/agent-core/src/services/question/question.ts
+++ b/packages/agent-core/src/services/question/question.ts
@@ -3,9 +3,7 @@
  *
  * **Service interface** (`IQuestionService`): Reverse-RPC one-shot broker
  * role — routes `QuestionRequest`s coming out of `PythinkerCore` to a waiter
- * (web client over WS, mock handler in tests) and resolves the
- * promise when the response arrives — or `dismiss()`-es it if the user
- * closes the panel (SCHEMAS.md §6.3).
+ * and resolves the promise when the response arrives or the user dismisses it.
  *
  * Role: one-shot broker — see `packages/services/AGENTS.md`. Kept under the
  * `Service` suffix per the package-wide convention; the broker semantics
@@ -13,36 +11,29 @@
  * docstring, not in the type name.
  *
  * **Shape note:** the service returns the in-process
- * `QuestionResult = null | QuestionAnswers | QuestionResponse` (see
- * `packages/agent-core/src/rpc/sdk-api.ts:48`). SCHEMAS.md §6.2/§6.4 defines
- * a protocol-level `QuestionResponse` with a 5-kind discriminated union
- * (`single` / `multi` / `other` / `multi_with_other` / `skipped`); the
- * protocol↔in-process adapter lives at the daemon boundary, NOT inside the
- * service interface. This keeps the SDK side of the adapter untouched and
- * confines protocol shape decisions to one place.
+ * `QuestionResult = null | QuestionAnswers | QuestionResponse`. The
+ * protocol↔in-process adapter lives at the daemon boundary, not inside the
+ * service interface.
  *
  * **Adapter** (`toBrokerRequest` / `toAgentCoreResponse` / `dismissedResult`):
- * Bridges two representations of the same question interaction:
+ * Bridges two representations of the same question interaction. Protocol ids
+ * go in; question text and option labels that the user saw come out. This is
+ * the only protocol↔SDK translation site for questions:
  *
  *   1. **In-process SDK shape** (agent-core, camelCase) — what
- *      `BridgeClientAPI` sees from `PythinkerCore.requestQuestion(...)`. See
- *      `packages/agent-core/src/rpc/sdk-api.ts:50-54`:
+ *      `BridgeClientAPI` sees from `PythinkerCore.requestQuestion(...)`:
  *        `QuestionRequest { turnId?, toolCallId?, questions: QuestionItem[] }`
  *      where `QuestionItem` has `question, header?, body?, options[],
  *      multiSelect?, allowOther?, otherLabel?, otherDescription?`.
  *      `QuestionResult = null | QuestionAnswers | QuestionResponse`,
  *      `QuestionAnswers = Record<string, string | true>`.
  *
- *   2. **Protocol wire shape** (snake_case, with daemon-allocated metadata) —
- *      defined in `packages/protocol/src/question.ts`. 5-kind discriminated
- *      union for answers: `single | multi | other | multi_with_other | skipped`.
+ *   2. **Protocol wire shape** (snake_case, with daemon-allocated metadata).
  *
  * **Synthesizing stable ids** (SDK has no per-item / per-option `id`):
  *   - `QuestionItem.id`     ← `q_<index>` (e.g. `q_0`, `q_1`, ...)
  *   - `QuestionOption.id`   ← `opt_<parent_idx>_<option_idx>` (e.g. `opt_0_0`)
  *
- * **Anti-corruption**: this is the ONLY place protocol↔SDK shape translation
- * happens for question.
  */
 
 import { createDecorator } from '../../di';
@@ -104,14 +95,14 @@ export interface QuestionToBrokerRequestParams {
   readonly sessionId: string;
   /** `createdAt` ISO string; broker passes `new Date().toISOString()`. */
   readonly createdAt: string;
-  /** `expiresAt` ISO string; broker computes `createdAt + 60s`. */
+  /** `expiresAt` ISO string; broker computes the lease deadline. */
   readonly expiresAt: string;
 }
 
 /**
  * Build a protocol option from an SDK option. SDK has only `label?:string` +
  * `description?:string`; we synthesize `id` from parent and child indices so
- * `toAgentCoreAnswers` can map back through `Record<qid, string>`.
+ * the response adapter can map answers back to the question text and labels.
  */
 function buildOption(
   opt: {
@@ -134,7 +125,7 @@ function buildOption(
 
 /**
  * Build a protocol question item from an SDK item + its position. The
- * synthesized `id` (`q_<parentIdx>`) is the key the SDK answers Record uses.
+ * synthesized `id` (`q_<parentIdx>`) identifies the matching response item.
  */
 function buildItem(
   item: InProcessQuestionItem,
@@ -178,36 +169,42 @@ export function toBrokerRequest(
 }
 
 /**
- * Protocol REST response body → in-process SDK `QuestionResponse` (with
- * `answers` flattened to `Record<string, string | true>`).
+ * Protocol response ids + the original request → in-process SDK
+ * `QuestionResponse` with answers flattened to `Record<string, string | true>`.
  *
- * Normalization rules from SCHEMAS §6.4:
- *   - single            → option_id
- *   - multi             → option_ids.join(',')
+ * The original request is the lookup for the text and labels displayed to the
+ * user:
+ *   - single            → option label
+ *   - multi             → option labels joined with `, `
  *   - other             → text
- *   - multi_with_other  → [...option_ids, other_text].join(',')
+ *   - multi_with_other  → option labels and text joined with `, `
  *   - skipped           → OMIT entry
  */
 export function toAgentCoreResponse(
   resp: ProtocolQuestionResponse,
+  request: ProtocolQuestionRequest,
 ): InProcessQuestionResponse {
   const flattened: InProcessQuestionAnswers = {};
   for (const [qid, ans] of Object.entries(resp.answers)) {
+    const item = request.questions.find((question) => question.id === qid);
+    const question = item?.question ?? qid;
+    const optionLabel = (id: string): string =>
+      item?.options.find((option) => option.id === id)?.label ?? id;
     switch (ans.kind) {
       case 'single':
-        flattened[qid] = ans.option_id;
+        flattened[question] = optionLabel(ans.option_id);
         break;
       case 'multi':
-        flattened[qid] = ans.option_ids.join(',');
+        flattened[question] = ans.option_ids.map(optionLabel).join(', ');
         break;
       case 'other':
-        flattened[qid] = ans.text;
+        flattened[question] = ans.text;
         break;
       case 'multi_with_other':
-        flattened[qid] = [...ans.option_ids, ans.other_text].join(',');
+        flattened[question] = [...ans.option_ids.map(optionLabel), ans.other_text].join(', ');
         break;
       case 'skipped':
-        // Omitted from the record — matches SCHEMAS §6.4 ("if skipped continue").
+        // Omitted from the record.
         break;
       default: {
         // Defensive: never-reached if Zod schema is the SOT, but TS narrowing
@@ -219,7 +216,7 @@ export function toAgentCoreResponse(
   }
   const out: InProcessQuestionResponse = { answers: flattened };
   if (resp.method !== undefined) {
-    // SCHEMAS §6.2 protocol allows 'click' as a method; agent-core's in-process
+    // Protocol allows 'click' as a method; agent-core's in-process
     // `QuestionAnswerMethod` is `'enter' | 'space' | 'number_key'` (NO 'click').
     // Drop 'click' on the in-process side to preserve type safety; the wire
     // form keeps it for clients that want to surface the affordance used.
diff --git a/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts b/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts
index 3352fd92..d0cd75e4 100644
--- a/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts
+++ b/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts
@@ -102,6 +102,8 @@ export const AskUserQuestionInputSchema: z.ZodType<AskUserQuestionInput> =
   AskUserQuestionInputBaseSchema;
 
 const QUESTION_DISMISSED_MESSAGE = 'User dismissed the question without answering.';
+const QUESTION_EXPIRED_MESSAGE =
+  'The question expired before the user answered it. The user did NOT dismiss it — ask again in your text response if you still need the answer.';
 
 const QUESTION_UNSUPPORTED_FAILURE_MESSAGE =
   'The connected client does not support interactive questions. Do NOT call this tool again. Ask the user directly in your text response instead.';
@@ -216,7 +218,23 @@ export class AskUserQuestionTool implements BuiltinTool<AskUserQuestionInput> {
         };
       }
 
-      return dismissedQuestionResult();
+      if (error instanceof PythinkerError && error.code === ErrorCodes.QUESTION_EXPIRED) {
+        const source = args.metadata?.source;
+        if (source === undefined) {
+          this.agent.telemetry.track('question_expired');
+        } else {
+          this.agent.telemetry.track('question_expired', { source });
+        }
+        return {
+          isError: false,
+          output: JSON.stringify({ answers: {}, note: QUESTION_EXPIRED_MESSAGE }),
+        };
+      }
+
+      return {
+        isError: true,
+        output: `The question could not be delivered or answered: ${errorMessage(error)}`,
+      };
     }
   }
 
diff --git a/packages/agent-core/test/services/question-adapter.test.ts b/packages/agent-core/test/services/question-adapter.test.ts
index 441b82de..1734a36c 100644
--- a/packages/agent-core/test/services/question-adapter.test.ts
+++ b/packages/agent-core/test/services/question-adapter.test.ts
@@ -1,8 +1,7 @@
 /**
  * Question adapter unit tests (W8.2 / Chain 6).
  *
- * Covers SCHEMAS §6.4 5-kind ↔ Record<string, string | true> normalization
- * verbatim.
+ * Covers protocol answer normalization into the text the user sees.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -103,74 +102,101 @@ describe('question-adapter · toBrokerRequest (in-process → protocol)', () =>
   });
 });
 
-describe('question-adapter · toAgentCoreResponse · SCHEMAS §6.4 verbatim', () => {
-  it("'single' → answers[qid] = option_id", () => {
+describe('question-adapter · toAgentCoreResponse (protocol ids → user-facing text)', () => {
+  const request = {
+    question_id: '01J_QUESTION',
+    session_id: 'sess_x',
+    questions: [
+      {
+        id: 'q_0',
+        question: 'Which animal?',
+        options: [
+          { id: 'opt_0_0', label: 'Cat' },
+          { id: 'opt_0_1', label: 'Dog' },
+        ],
+      },
+      {
+        id: 'q_1',
+        question: 'Which colors?',
+        options: [
+          { id: 'opt_1_0', label: 'Red' },
+          { id: 'opt_1_1', label: 'Green' },
+          { id: 'opt_1_2', label: 'Blue' },
+        ],
+      },
+    ],
+    created_at: '2026-06-04T10:30:00.000Z',
+    expires_at: '2026-06-04T11:00:00.000Z',
+  };
+
+  it("'single' maps the question text to the option label", () => {
     const inProc = toAgentCoreResponse({
       answers: { q_0: { kind: 'single', option_id: 'opt_0_1' } },
-    });
-    expect(inProc.answers).toEqual({ q_0: 'opt_0_1' });
+    }, request);
+    expect(inProc.answers).toEqual({ 'Which animal?': 'Dog' });
   });
 
-  it("'multi' → answers[qid] = option_ids.join(',')  (lossy)", () => {
+  it("'multi' maps option ids to labels", () => {
     const inProc = toAgentCoreResponse({
       answers: {
-        q_0: { kind: 'multi', option_ids: ['opt_0_0', 'opt_0_2'] },
+        q_1: { kind: 'multi', option_ids: ['opt_1_0', 'opt_1_2'] },
       },
-    });
-    expect(inProc.answers).toEqual({ q_0: 'opt_0_0,opt_0_2' });
+    }, request);
+    expect(inProc.answers).toEqual({ 'Which colors?': 'Red, Blue' });
   });
 
-  it("'other' → answers[qid] = text", () => {
+  it("'other' keeps the entered text", () => {
     const inProc = toAgentCoreResponse({
       answers: { q_0: { kind: 'other', text: 'Hippopotamus' } },
-    });
-    expect(inProc.answers).toEqual({ q_0: 'Hippopotamus' });
+    }, request);
+    expect(inProc.answers).toEqual({ 'Which animal?': 'Hippopotamus' });
   });
 
-  it("'multi_with_other' → [...option_ids, other_text].join(',')", () => {
+  it("'multi_with_other' maps labels and keeps the entered text", () => {
     const inProc = toAgentCoreResponse({
       answers: {
-        q_0: {
+        q_1: {
           kind: 'multi_with_other',
-          option_ids: ['opt_0_0', 'opt_0_1'],
+          option_ids: ['opt_1_0', 'opt_1_1'],
           other_text: 'Custom',
         },
       },
-    });
-    expect(inProc.answers).toEqual({ q_0: 'opt_0_0,opt_0_1,Custom' });
+    }, request);
+    expect(inProc.answers).toEqual({ 'Which colors?': 'Red, Green, Custom' });
   });
 
-  it("'skipped' → entry OMITTED entirely from the record", () => {
+  it("'skipped' omits the answer", () => {
     const inProc = toAgentCoreResponse({
       answers: {
         q_0: { kind: 'single', option_id: 'opt_0_0' },
         q_1: { kind: 'skipped' },
-        q_2: { kind: 'other', text: 'Custom' },
       },
-    });
+    }, request);
     expect(inProc.answers).toEqual({
-      q_0: 'opt_0_0',
-      q_2: 'Custom',
+      'Which animal?': 'Cat',
     });
-    expect(Object.keys(inProc.answers)).not.toContain('q_1');
+    expect(Object.keys(inProc.answers)).not.toContain('Which colors?');
   });
 
-  it('handles a mixed 4-item response with one skipped (e2e prompt acceptance)', () => {
+  it('falls back to raw ids for unknown questions and options', () => {
     const inProc = toAgentCoreResponse({
       answers: {
-        q_0: { kind: 'single', option_id: 'opt_0_0' },
-        q_1: { kind: 'multi', option_ids: ['opt_1_0', 'opt_1_1'] },
-        q_2: { kind: 'other', text: 'Hippopotamus' },
-        q_3: { kind: 'skipped' },
+        q_0: { kind: 'single', option_id: 'opt_0_unknown' },
+        q_unknown: { kind: 'single', option_id: 'opt_unknown' },
       },
-      method: 'click',
-    });
+    }, request);
     expect(inProc.answers).toEqual({
-      q_0: 'opt_0_0',
-      q_1: 'opt_1_0,opt_1_1',
-      q_2: 'Hippopotamus',
+      'Which animal?': 'opt_0_unknown',
+      q_unknown: 'opt_unknown',
     });
-    // method 'click' is NOT in agent-core's in-process method union — dropped.
+  });
+
+  it("drops the protocol-only 'click' method", () => {
+    const inProc = toAgentCoreResponse({
+      answers: { q_0: { kind: 'single', option_id: 'opt_0_0' } },
+      method: 'click',
+    }, request);
+    expect(inProc.answers).toEqual({ 'Which animal?': 'Cat' });
     expect((inProc as { method?: string }).method).toBeUndefined();
   });
 
@@ -178,7 +204,7 @@ describe('question-adapter · toAgentCoreResponse · SCHEMAS §6.4 verbatim', ()
     const inProc = toAgentCoreResponse({
       answers: { q_0: { kind: 'skipped' } },
       method: 'enter',
-    });
+    }, request);
     expect((inProc as { method?: string }).method).toBe('enter');
   });
 
@@ -191,7 +217,7 @@ describe('question-adapter · toAgentCoreResponse · SCHEMAS §6.4 verbatim', ()
           notes: 'Use the calmer option.',
         },
       },
-    });
+    }, request);
 
     expect(inProc.annotations).toEqual({
       'Which animal?': {
@@ -207,7 +233,7 @@ describe('question-adapter · toAgentCoreResponse · SCHEMAS §6.4 verbatim', ()
         q_0: { kind: 'skipped' },
         q_1: { kind: 'skipped' },
       },
-    });
+    }, request);
     expect(inProc.answers).toEqual({});
     // Distinct from dismissedResult() which returns null.
     expect(inProc).not.toBeNull();
diff --git a/packages/agent-core/test/tools/ask-user.test.ts b/packages/agent-core/test/tools/ask-user.test.ts
index ca28c276..418ffd29 100644
--- a/packages/agent-core/test/tools/ask-user.test.ts
+++ b/packages/agent-core/test/tools/ask-user.test.ts
@@ -390,7 +390,7 @@ describe('AskUserQuestionTool', () => {
     expect(telemetryTrack).toHaveBeenCalledWith('question_dismissed');
   });
 
-  it('resolves question rpc error responses as dismissed answers', async () => {
+  it('returns an error when question rpc delivery fails', async () => {
     const { tool } = makeTool({
       requestQuestion: async () => {
         throw new PythinkerError(ErrorCodes.INTERNAL, 'JSON-RPC question error response');
@@ -404,17 +404,33 @@ describe('AskUserQuestionTool', () => {
       signal,
     });
 
-    expect(result).toMatchObject({ isError: false });
-    expect(result.output).toContain('dismissed');
-    expect(typeof result.output).toBe('string');
-    const output = typeof result.output === 'string' ? result.output : '';
-    expect(JSON.parse(output)).toEqual({
-      answers: {},
-      note: 'User dismissed the question without answering.',
-    });
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('could not be delivered or answered');
+    expect(result.output).toContain('JSON-RPC question error response');
+    expect(result.output).not.toContain('dismissed');
     expect(result.output).not.toContain('Do NOT call this tool again');
   });
 
+  it('returns an expired question note without marking it dismissed', async () => {
+    const { tool, telemetryTrack } = makeTool({
+      requestQuestion: async () => {
+        throw new PythinkerError(ErrorCodes.QUESTION_EXPIRED, 'question expired');
+      },
+    });
+
+    const result = await executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'call_question',
+      args: { ...input(), metadata: { source: 'test' } },
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('expired');
+    expect(result.output).not.toContain('dismissed');
+    expect(telemetryTrack).toHaveBeenCalledWith('question_expired', { source: 'test' });
+  });
+
   it('propagates aborts while waiting for question rpc', async () => {
     const controller = new AbortController();
     const { tool } = makeTool({
diff --git a/packages/protocol/src/events.ts b/packages/protocol/src/events.ts
index 61ad40d3..0758d9d9 100644
--- a/packages/protocol/src/events.ts
+++ b/packages/protocol/src/events.ts
@@ -207,6 +207,7 @@ export type PythinkerErrorCode =
   | 'session.init_failed'
   | 'agent.not_found'
   | 'turn.agent_busy'
+  | 'question.expired'
   | 'goal.already_exists'
   | 'goal.not_found'
   | 'goal.objective_empty'
diff --git a/packages/server/src/routes/questions.ts b/packages/server/src/routes/questions.ts
index fc37bf29..94939612 100644
--- a/packages/server/src/routes/questions.ts
+++ b/packages/server/src/routes/questions.ts
@@ -39,7 +39,7 @@ import {
   questionResolveRequestSchema,
   questionResolveResultSchema,
 } from '@pymodel/protocol';
-import { IQuestionService, questionToAgentCoreResponse, type IInstantiationService } from '@pymodel/agent-core';
+import { IQuestionService, type IInstantiationService } from '@pymodel/agent-core';
 import { z } from 'zod';
 
 
@@ -226,9 +226,16 @@ export function registerQuestionsRoutes(
       }
 
       const body = bodyParse.data;
-      const inProc = questionToAgentCoreResponse(body);
-      broker.resolve(questionId, inProc);
-      broker.markResolved(questionId);
+      if (!broker.resolveProtocolResponse(questionId, body)) {
+        reply.send(
+          errEnvelope(
+            ErrorCode.QUESTION_NOT_FOUND,
+            `question ${questionId} not found`,
+            req.id,
+          ),
+        );
+        return;
+      }
 
       const result = {
         resolved: true,
diff --git a/packages/server/src/services/question/questionService.ts b/packages/server/src/services/question/questionService.ts
index 0439f4ff..af90a088 100644
--- a/packages/server/src/services/question/questionService.ts
+++ b/packages/server/src/services/question/questionService.ts
@@ -2,23 +2,25 @@
 
 import { ulid } from 'ulid';
 
-import { Disposable, DisposableMap, IEventService, IQuestionService, questionDismissedResult, questionToBrokerRequest, ILogService, type IDisposable, type QuestionRequest, type QuestionResult } from '@pymodel/agent-core';
+import { Disposable, DisposableMap, ErrorCodes, IEventService, PythinkerError, questionDismissedResult, questionToAgentCoreResponse, questionToBrokerRequest, ILogService, type IDisposable, type IQuestionService, type QuestionRequest, type QuestionResult } from '@pymodel/agent-core';
 import type {
   Event,
   QuestionRequest as ProtocolQuestionRequest,
+  QuestionResponse as ProtocolQuestionResponse,
 } from '@pymodel/protocol';
 
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _typeAnchor: typeof IQuestionService = IQuestionService;
-
-export const QUESTION_DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * A pending question waits on a human, so the timer is a leak guard, not a
+ * network timeout. Keep it long enough that a person can read the options,
+ * think, and answer without losing the turn.
+ */
+export const QUESTION_DEFAULT_TIMEOUT_MS = 30 * 60_000;
 
 export const QUESTION_RECENTLY_RESOLVED_CAP = 1024;
 
-export class QuestionExpiredError extends Error {
+export class QuestionExpiredError extends PythinkerError {
   constructor(public readonly questionId: string, timeoutMs: number) {
-    super(`question ${questionId} expired after ${timeoutMs}ms`);
+    super(ErrorCodes.QUESTION_EXPIRED, `question ${questionId} expired after ${timeoutMs}ms`);
     this.name = 'QuestionExpiredError';
   }
 }
@@ -160,6 +162,19 @@ export class QuestionService extends Disposable implements IQuestionService {
     p.resolve(response);
   }
 
+  /**
+   * Resolve a pending question from its protocol response. The adapter needs
+   * the original request to turn ids back into the question text and option
+   * labels the user saw, and the pending entry is the only holder of it.
+   * Returns false when the question is not pending.
+   */
+  resolveProtocolResponse(id: string, response: ProtocolQuestionResponse): boolean {
+    const p = this._pending.get(id);
+    if (!p) return false;
+    this.resolve(id, questionToAgentCoreResponse(response, p.protocolRequest));
+    return true;
+  }
+
   dismiss(id: string): void {
     const p = this._pending.get(id);
     if (!p) return;
diff --git a/packages/server/test/question.e2e.test.ts b/packages/server/test/question.e2e.test.ts
index 4133a188..fdcf2796 100644
--- a/packages/server/test/question.e2e.test.ts
+++ b/packages/server/test/question.e2e.test.ts
@@ -239,7 +239,7 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
     expect(env.code).toBe(0);
     expect(env.data?.resolved).toBe(true);
 
-    // Promise resolves with the SCHEMAS §6.4 flattened shape.
+    // Promise resolves with the text and labels that the user saw.
     const result = await pending;
     expect(result).not.toBeNull();
     const inProcResp = result as {
@@ -247,16 +247,45 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
       method?: string;
     };
     expect(inProcResp.answers).toEqual({
-      q_0: 'opt_0_0',
-      q_1: 'opt_1_0,opt_1_2',
-      q_2: 'Hippopotamus',
-      // q_3 omitted entirely (kind: skipped)
+      'Animal?': 'Cat',
+      'Colors?': 'R, B',
+      'Custom?': 'Hippopotamus',
+      // 'Skip me' omitted entirely (kind: skipped)
     });
     expect(inProcResp.method).toBe('enter');
 
     ws.close();
   });
 
+  it('REST resolve gives the awaiting caller question text and option labels', async () => {
+    const r = await bootDaemon();
+    const sid = await createSession(r);
+    const broker = r.services.invokeFunction(
+      (a) => a.get(IQuestionService) as QuestionService,
+    );
+    const pending = broker.request({
+      sessionId: sid,
+      agentId: 'main',
+      questions: [
+        { question: 'Which animal?', options: [{ label: 'Cat' }, { label: 'Dog' }] },
+      ],
+    });
+    const questionId = firstPendingQuestionId(broker);
+    expect(questionId).toBeDefined();
+    if (questionId === undefined) throw new Error('pending question id is missing');
+
+    const res = await appOf(r).inject({
+      method: 'POST',
+      url: `/api/v1/sessions/${sid}/questions/${questionId}`,
+      payload: { answers: { q_0: { kind: 'single', option_id: 'opt_0_1' } } },
+    });
+
+    expect(envelopeOf<{ resolved: boolean }>(res.json()).code).toBe(0);
+    await expect(pending).resolves.toEqual({
+      answers: { 'Which animal?': 'Dog' },
+    });
+  });
+
   it('GET pending questions lists recoverable requests and omits dismissed ones', async () => {
     const r = await bootDaemon();
     const sid = await createSession(r);
@@ -364,19 +393,19 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
       'single kind',
       [{ question: '?', options: [{ label: 'A' }, { label: 'B' }] }],
       { q_0: { kind: 'single', option_id: 'opt_0_1' } },
-      { q_0: 'opt_0_1' },
+      { '?': 'B' },
     ],
     [
       'multi kind',
       [{ question: '?', options: [{ label: 'A' }, { label: 'B' }, { label: 'C' }], multiSelect: true }],
       { q_0: { kind: 'multi', option_ids: ['opt_0_0', 'opt_0_2'] } },
-      { q_0: 'opt_0_0,opt_0_2' },
+      { '?': 'A, C' },
     ],
     [
       'other kind',
       [{ question: '?', options: [{ label: 'X' }, { label: 'Y' }], otherLabel: 'Other' }],
       { q_0: { kind: 'other', text: 'free' } },
-      { q_0: 'free' },
+      { '?': 'free' },
     ],
     [
       'multi_with_other kind',
@@ -388,7 +417,7 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
           other_text: 'X',
         },
       },
-      { q_0: 'opt_0_0,X' },
+      { '?': 'A, X' },
     ],
     [
       'skipped kind (record entry omitted)',
@@ -397,7 +426,7 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
       {},
     ],
   ] as const)(
-    'normalizes %s per SCHEMAS §6.4',
+    'normalizes %s to the text and labels shown to the user',
     async (_label, questions, answers, expectedRecord) => {
       const r = await bootDaemon();
       const sid = await createSession(r);
@@ -588,7 +617,7 @@ describe('Question reverse-RPC: WS broadcast → REST resolve → Promise settle
     broker.dismiss(questionId!);
   });
 
-  it('60s timeout broadcasts event.question.expired + rejects with QuestionExpiredError', async () => {
+  it('lease expiry broadcasts event.question.expired + rejects with QuestionExpiredError', async () => {
     const r = await bootDaemon();
     const sid = await createSession(r);
     const { ws, received } = await openSubscriber(r, sid);
diff --git a/packages/server/test/services.test.ts b/packages/server/test/services.test.ts
index 50b6d473..2d7dae30 100644
--- a/packages/server/test/services.test.ts
+++ b/packages/server/test/services.test.ts
@@ -7,7 +7,7 @@ import { join } from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { InstantiationService, ServiceCollection, EventService, FsWatcherService, IApprovalService, IEventService, ILogService, IQuestionService, type ApprovalResponse, type QuestionResult, type FsWatcherServiceOptions, type IEnvironmentService, type ILogService as ILoggerT, type ISessionService } from '@pymodel/agent-core';
+import { InstantiationService, ServiceCollection, EventService, ErrorCodes, FsWatcherService, IApprovalService, IEventService, ILogService, IQuestionService, type ApprovalResponse, type QuestionResult, type FsWatcherServiceOptions, type IEnvironmentService, type ILogService as ILoggerT, type ISessionService } from '@pymodel/agent-core';
 import { WS_PROTOCOL_VERSION, type Event } from '@pymodel/protocol';
 
 import { ApprovalService } from '#/services/approval/approvalService';
@@ -1172,7 +1172,7 @@ describe('QuestionService (broadcasts + dismiss)', () => {
     bus.dispose();
   });
 
-  it('60s timeout broadcasts event.question.expired + rejects QuestionExpiredError', async () => {
+  it('lease expiry broadcasts event.question.expired + rejects QuestionExpiredError', async () => {
     const { broker, bus, broadcast, conn } = makeQuestionBroker();
     broker._setTimeoutMsForTests(30);
     const pending = broker.request({
@@ -1184,6 +1184,7 @@ describe('QuestionService (broadcasts + dismiss)', () => {
     } as Parameters<typeof broker.request>[0]);
 
     await expect(pending).rejects.toMatchObject({ name: 'QuestionExpiredError' });
+    await expect(pending).rejects.toHaveProperty('code', ErrorCodes.QUESTION_EXPIRED);
     await broadcast._drainForTest('s');
     const expiredFrame = conn.sent.find(
       (f) => (f as { type: string }).type === 'event.question.expired',

From a0853fe042492753ec53a0008b4e943a2a16b1e4 Mon Sep 17 00:00:00 2001
From: elkaix <melkholy@techmatrix.com>
Date: Sun, 16 Aug 2026 05:12:08 -0400
Subject: [PATCH 2/4] fix(desktop): pin the Host to a fixed loopback port

An OS-assigned port changed on every launch, so the web origin changed with it
and browser-stored settings were lost. The Host now binds a fixed port, with a
PYTHINKER_DESKTOP_PORT override and a retry dialog when the port is busy.
The updater also reports updates as unavailable when a packaged build has no
app-update.yml.
---
 .changeset/desktop-fixed-port.md           |  5 ++
 apps/desktop/src/host-supervisor.ts        | 26 ++++++++-
 apps/desktop/src/main.ts                   | 64 +++++++++++++++-------
 apps/desktop/src/updater.ts                | 23 +++++++-
 apps/desktop/tests/host-supervisor.spec.ts | 35 +++++++++++-
 apps/desktop/tests/updater.spec.ts         | 46 +++++++++++++++-
 6 files changed, 173 insertions(+), 26 deletions(-)
 create mode 100644 .changeset/desktop-fixed-port.md

diff --git a/.changeset/desktop-fixed-port.md b/.changeset/desktop-fixed-port.md
new file mode 100644
index 00000000..ebb09104
--- /dev/null
+++ b/.changeset/desktop-fixed-port.md
@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": minor
+---
+
+The desktop app now uses a fixed loopback port so browser-stored settings persist between launches, shows a retry dialog when that port is occupied, and reports updates as unavailable for builds packaged without an update feed.
diff --git a/apps/desktop/src/host-supervisor.ts b/apps/desktop/src/host-supervisor.ts
index 89f525c8..2d40ee7c 100644
--- a/apps/desktop/src/host-supervisor.ts
+++ b/apps/desktop/src/host-supervisor.ts
@@ -9,6 +9,26 @@ const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
 const TASKKILL_TIMEOUT_MS = 5_000
 const MAX_STARTUP_OUTPUT_CHARS = 32_768
 
+export const DESKTOP_PACKAGED_PORT = 24_827
+export const DESKTOP_DEV_PORT = 24_828
+
+/** Resolve the fixed Host port, with an optional validated environment override. */
+export function resolveDesktopPort(env: NodeJS.ProcessEnv, isPackaged: boolean): number {
+  const value = env['PYTHINKER_DESKTOP_PORT']
+  if (value === undefined) return isPackaged ? DESKTOP_PACKAGED_PORT : DESKTOP_DEV_PORT
+
+  const port = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(`PYTHINKER_DESKTOP_PORT must be an integer from 1 to 65535; received ${JSON.stringify(value)}`)
+  }
+  return port
+}
+
+/** Return whether Host output reports that its fixed port is already occupied. */
+export function isPortInUseError(message: string): boolean {
+  return /EADDRINUSE|address already in use/iu.test(message)
+}
+
 /** Incremental parser for the Web Host's canonical readiness line. */
 export interface ReadinessParser {
   /**
@@ -257,6 +277,8 @@ export interface SpawnPythinkerServerOptions {
   readonly cwd: string
   /** Frozen environment for the Host process. */
   readonly env: NodeJS.ProcessEnv
+  /** Fixed loopback port for the Host server. */
+  readonly port: number
   /** Run the Electron executable as its bundled Node runtime. */
   readonly electronRunAsNode?: boolean
 }
@@ -272,7 +294,7 @@ function streamAdapter(stream: NodeJS.ReadableStream): HostChild['stdout'] {
 }
 
 /**
- * Spawn the production Pythinker server on an OS-assigned loopback port.
+ * Spawn the production Pythinker server on a fixed loopback port.
  * @param options - Node runtime, built CLI and process environment.
  * @returns The child handle consumed by {@link createHostSupervisor}.
  */
@@ -286,7 +308,7 @@ export function spawnPythinkerServer(options: SpawnPythinkerServerOptions): Host
     'run',
     '--foreground',
     '--port',
-    '0',
+    String(options.port),
     '--log-level',
     'error',
   ], {
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 30522f41..bed37ad7 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -23,7 +23,13 @@ import {
   setCrashPhase,
   track,
 } from '@pymodel/pythinker-telemetry'
-import { createHostSupervisor, spawnPythinkerServer, type HostSupervisor } from './host-supervisor'
+import {
+  createHostSupervisor,
+  isPortInUseError,
+  resolveDesktopPort,
+  spawnPythinkerServer,
+  type HostSupervisor,
+} from './host-supervisor'
 import { createSplashWindow } from './splash'
 import {
   checkForUpdatesNow,
@@ -302,6 +308,7 @@ async function boot(): Promise<void> {
   if (bootQuitPromise !== undefined) return
   initializeDesktopTelemetry()
   const paths = hostPaths()
+  const port = resolveDesktopPort(process.env, app.isPackaged)
   assertHostArtifacts(paths)
   const splash = createSplashWindow(desktopResources('splash'))
   const destroySplash = (): void => {
@@ -312,26 +319,43 @@ async function boot(): Promise<void> {
     const trayFrames = loadTrayImages()
     createTray(trayFrames)
     stopTrayAnimation = startTrayAnimation(trayFrames)
-    host = createHostSupervisor({
-      spawnHost: () => spawnPythinkerServer({
-        ...paths,
-        env: {
-          ...process.env,
-          PYTHINKER_DESKTOP: '1',
+    for (;;) {
+      host = createHostSupervisor({
+        spawnHost: () => spawnPythinkerServer({
+          ...paths,
+          env: {
+            ...process.env,
+            PYTHINKER_DESKTOP: '1',
+          },
+          port,
+        }),
+        log: chunk => process.stderr.write(chunk),
+        onUnexpectedExit: ({ code, signal }) => {
+          console.error(`desktop Host exited unexpectedly (code ${String(code)}, signal ${String(signal)})`)
+          void requestAppQuit()
         },
-      }),
-      log: chunk => process.stderr.write(chunk),
-      onUnexpectedExit: ({ code, signal }) => {
-        console.error(`desktop Host exited unexpectedly (code ${String(code)}, signal ${String(signal)})`)
-        void requestAppQuit()
-      },
-    })
-    try {
-      hostOrigin = await host.start()
-      track('desktop_server_ready')
-    } catch (error) {
-      track('desktop_server_failed')
-      throw error
+      })
+      try {
+        hostOrigin = await host.start()
+        track('desktop_server_ready')
+        break
+      } catch (error) {
+        track('desktop_server_failed')
+        const message = error instanceof Error ? error.message : String(error)
+        if (!isPortInUseError(message)) throw error
+
+        const result = await dialog.showMessageBox({
+          type: 'error',
+          buttons: ['Retry', 'Quit'],
+          defaultId: 0,
+          cancelId: 1,
+          title: `${APP_NAME} needs its fixed port`,
+          message: `${APP_NAME} cannot use port ${String(port)}. It needs this fixed port so settings persist between launches. Free the port, or set PYTHINKER_DESKTOP_PORT to an unused port.`,
+        })
+        if (result.response === 0) continue
+        await requestAppQuit()
+        return
+      }
     }
     stopTrayAnimation?.()
     stopTrayAnimation = undefined
diff --git a/apps/desktop/src/updater.ts b/apps/desktop/src/updater.ts
index cd6ebd4a..803f625e 100644
--- a/apps/desktop/src/updater.ts
+++ b/apps/desktop/src/updater.ts
@@ -1,10 +1,11 @@
-import { readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { app, type BrowserWindow } from 'electron'
 import electronUpdater from 'electron-updater'
 
 const { autoUpdater } = electronUpdater
 const UPDATE_SETTINGS_FILE = 'update-settings.json'
+const UPDATES_UNAVAILABLE_MESSAGE = 'Updates are not available for this build'
 const INITIAL_CHECK_DELAY_MS = 10_000
 const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1_000
 
@@ -117,6 +118,20 @@ function clearTimers(): void {
   checkInterval = undefined
 }
 
+function hasUpdateConfig(): boolean {
+  return existsSync(join(process.resourcesPath, 'app-update.yml'))
+}
+
+function disableUpdates(): UpdateState {
+  updateState({
+    status: 'disabled',
+    message: UPDATES_UNAVAILABLE_MESSAGE,
+    version: undefined,
+    percent: undefined,
+  })
+  return state
+}
+
 function scheduleChecks(): void {
   if (checkInterval !== undefined) return
   checkInterval = setInterval(() => {
@@ -181,6 +196,10 @@ export function initUpdater(
   clearTimers()
 
   if (!app.isPackaged) return
+  if (!hasUpdateConfig()) {
+    disableUpdates()
+    return
+  }
 
   try {
     autoUpdater.autoDownload = settings.autoUpdate
@@ -232,6 +251,7 @@ export async function checkForUpdatesNow(): Promise<UpdateState> {
     updateState({ status: 'disabled' })
     return state
   }
+  if (!hasUpdateConfig()) return disableUpdates()
 
   try {
     autoUpdater.autoDownload = true
@@ -251,6 +271,7 @@ export function quitAndInstallNow(): UpdateState {
     updateState({ status: 'disabled' })
     return state
   }
+  if (!hasUpdateConfig()) return disableUpdates()
 
   try {
     updateTelemetryTrack('desktop_update_install')
diff --git a/apps/desktop/tests/host-supervisor.spec.ts b/apps/desktop/tests/host-supervisor.spec.ts
index c347f3dd..ff08b9c0 100644
--- a/apps/desktop/tests/host-supervisor.spec.ts
+++ b/apps/desktop/tests/host-supervisor.spec.ts
@@ -5,6 +5,7 @@ import {
   createReadinessParser,
   type HostChild,
 } from '../src/host-supervisor'
+import * as hostSupervisor from '../src/host-supervisor'
 
 vi.mock('node:child_process', { spy: true })
 
@@ -112,6 +113,34 @@ describe('desktop Host readiness', () => {
   })
 })
 
+describe('desktop Host port', () => {
+  it('uses fixed ports for packaged and development builds without an override', () => {
+    expect(hostSupervisor.DESKTOP_PACKAGED_PORT).toBe(24_827)
+    expect(hostSupervisor.DESKTOP_DEV_PORT).toBe(24_828)
+    expect(hostSupervisor.resolveDesktopPort({}, true)).toBe(24_827)
+    expect(hostSupervisor.resolveDesktopPort({}, false)).toBe(24_828)
+  })
+
+  it('uses a valid port override for packaged and development builds', () => {
+    const env = { PYTHINKER_DESKTOP_PORT: '45231' }
+
+    expect(hostSupervisor.resolveDesktopPort(env, true)).toBe(45_231)
+    expect(hostSupervisor.resolveDesktopPort(env, false)).toBe(45_231)
+  })
+
+  it.each(['not-a-port', '70000'])('rejects an invalid port override: %s', (value) => {
+    expect(() => hostSupervisor.resolveDesktopPort({ PYTHINKER_DESKTOP_PORT: value }, true))
+      .toThrow(new RegExp(`PYTHINKER_DESKTOP_PORT.*${value}`, 'u'))
+  })
+
+  it('detects output that reports a port collision', () => {
+    expect(hostSupervisor.isPortInUseError(
+      'listen EADDRINUSE: address already in use 127.0.0.1:24827',
+    )).toBe(true)
+    expect(hostSupervisor.isPortInUseError('desktop Host exited before readiness (code 1, signal null)')).toBe(false)
+  })
+})
+
 describe('desktop Host supervisor', () => {
   it('starts one child for concurrent callers and returns its stdout readiness URL', async () => {
     const child = new FakeHostChild()
@@ -296,6 +325,7 @@ describe('desktop Host process', () => {
       cliEntry: '/Applications/Pythinker.app/Contents/Resources/host/node_modules/@pymodel/pythinker-code/dist/launcher.mjs',
       cwd: '/Users/tester',
       env: { PYTHINKER_DESKTOP: '1' },
+      port: 24_827,
       electronRunAsNode: true,
     })
 
@@ -307,7 +337,7 @@ describe('desktop Host process', () => {
         'run',
         '--foreground',
         '--port',
-        '0',
+        '24827',
         '--log-level',
         'error',
       ],
@@ -341,6 +371,7 @@ describe('desktop Host process', () => {
       cliEntry: '/tmp/launcher.mjs',
       cwd: '/tmp',
       env: {},
+      port: 24_827,
     })
     host.kill('SIGTERM')
 
@@ -379,6 +410,7 @@ describe('desktop Host process', () => {
       cliEntry: '/tmp/launcher.mjs',
       cwd: '/tmp',
       env: {},
+      port: 24_827,
     })
     host.kill('SIGTERM')
 
@@ -404,6 +436,7 @@ describe('desktop Host process', () => {
       cliEntry: '/tmp/launcher.mjs',
       cwd: '/tmp',
       env: {},
+      port: 24_827,
     })
     host.kill('SIGTERM')
 
diff --git a/apps/desktop/tests/updater.spec.ts b/apps/desktop/tests/updater.spec.ts
index 232c50ae..c26899d9 100644
--- a/apps/desktop/tests/updater.spec.ts
+++ b/apps/desktop/tests/updater.spec.ts
@@ -6,15 +6,26 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 vi.mock('electron', () => ({
   app: {
     isPackaged: false,
-    getPath: () => '',
+    getPath: vi.fn(() => ''),
+    once: vi.fn(),
   },
 }))
 
 vi.mock('electron-updater', () => ({
-  default: { autoUpdater: {} },
+  default: {
+    autoUpdater: {
+      on: vi.fn(),
+      checkForUpdates: vi.fn(),
+      quitAndInstall: vi.fn(),
+    },
+  },
 }))
 
+import { app } from 'electron'
+import electronUpdater from 'electron-updater'
 import {
+  getUpdateState,
+  initUpdater,
   readUpdateSettings,
   trackUpdateTransition,
   writeUpdateSettings,
@@ -22,11 +33,22 @@ import {
 } from '../src/updater'
 
 const temporaryDirectories: string[] = []
+const resourcesPathDescriptor = Object.getOwnPropertyDescriptor(process, 'resourcesPath')
+const { autoUpdater } = electronUpdater
 
 afterEach(() => {
   for (const directory of temporaryDirectories.splice(0)) {
     rmSync(directory, { recursive: true, force: true })
   }
+  Object.defineProperty(app, 'isPackaged', { configurable: true, value: false })
+  vi.mocked(app.getPath).mockReset()
+  vi.mocked(app.getPath).mockReturnValue('')
+  if (resourcesPathDescriptor === undefined) {
+    Reflect.deleteProperty(process, 'resourcesPath')
+  } else {
+    Object.defineProperty(process, 'resourcesPath', resourcesPathDescriptor)
+  }
+  vi.clearAllMocks()
 })
 
 function temporaryDirectory(): string {
@@ -76,3 +98,23 @@ describe('update telemetry transitions', () => {
     ])
   })
 })
+
+describe('packaged builds without update metadata', () => {
+  it('disables updates without wiring updater events', () => {
+    const directory = temporaryDirectory()
+    writeUpdateSettings(directory, { autoUpdate: false })
+    vi.mocked(app.getPath).mockReturnValue(directory)
+    Object.defineProperty(app, 'isPackaged', { configurable: true, value: true })
+    Object.defineProperty(process, 'resourcesPath', { configurable: true, value: directory })
+
+    initUpdater(() => undefined)
+
+    expect(getUpdateState()).toMatchObject({
+      status: 'disabled',
+      message: 'Updates are not available for this build',
+      autoUpdate: false,
+    })
+    expect(autoUpdater.on).not.toHaveBeenCalled()
+    expect(app.once).not.toHaveBeenCalled()
+  })
+})

From 86825b8ed5094fa8746457b5ef948dce961b9402 Mon Sep 17 00:00:00 2001
From: elkaix <melkholy@techmatrix.com>
Date: Sun, 16 Aug 2026 05:12:09 -0400
Subject: [PATCH 3/4] feat(site): add an animated particle field to the landing
 page

---
 apps/site/src/App.vue                      | 125 +++++++++++------
 apps/site/src/components/ParticleField.vue | 156 +++++++++++++++++++++
 2 files changed, 242 insertions(+), 39 deletions(-)
 create mode 100644 apps/site/src/components/ParticleField.vue

diff --git a/apps/site/src/App.vue b/apps/site/src/App.vue
index 298ed76b..87ea378e 100644
--- a/apps/site/src/App.vue
+++ b/apps/site/src/App.vue
@@ -3,10 +3,34 @@ import { onMounted, onUnmounted, ref } from 'vue';
 import AgentLoop from './components/AgentLoop.vue';
 import InstallCommand from './components/InstallCommand.vue';
 import LegacyDownloadsPopup from './components/LegacyDownloadsPopup.vue';
+import ParticleField from './components/ParticleField.vue';
 import PythinkerMascot from './components/PythinkerMascot.vue';
 
 const version = __PYTHINKER_VERSION__;
 
+// Desktop builds ship under their own git tag, so the repository's default "latest release"
+// URL resolves to the CLI release instead. Bump this when a new desktop version is published.
+const DESKTOP_VERSION = '0.1.0';
+const DESKTOP_RELEASE_URL = `https://github.com/PyModel/pythinker-code/releases/tag/v${DESKTOP_VERSION}`;
+const DESKTOP_DOWNLOADS = [
+  {
+    id: 'mac',
+    label: 'Download for macOS',
+    note: 'Apple Silicon · .dmg',
+    icon: '/brand/apple.svg',
+    href: `https://github.com/PyModel/pythinker-code/releases/download/v${DESKTOP_VERSION}/Pythinker-${DESKTOP_VERSION}-arm64.dmg`,
+  },
+  {
+    id: 'windows',
+    label: 'Download for Windows',
+    note: 'x64 · installer',
+    icon: '/brand/windows11.svg',
+    href: `https://github.com/PyModel/pythinker-code/releases/download/v${DESKTOP_VERSION}/Pythinker-${DESKTOP_VERSION}-x64-Setup.exe`,
+  },
+];
+const isWindows = /Win/i.test(navigator.platform || navigator.userAgent);
+const desktopDownloads = isWindows ? [...DESKTOP_DOWNLOADS].reverse() : DESKTOP_DOWNLOADS;
+
 const installRows = [
   ['macOS / Linux', 'curl -fsSL https://code.pythinker.com/pythinker-code/install.sh | bash', '/brand/apple.svg'],
   ['Windows (PowerShell)', 'irm https://code.pythinker.com/pythinker-code/install.ps1 | iex', '/brand/windows11.svg'],
@@ -198,6 +222,7 @@ onUnmounted(() => {
 </script>
 
 <template>
+  <ParticleField />
   <nav class="site-nav" aria-label="Primary navigation">
     <div class="container nav-inner">
       <a href="/" class="nav-brand"><PythinkerMascot :width="26" :height="32" /><span>Pythinker Code</span></a>
@@ -232,27 +257,30 @@ onUnmounted(() => {
         <PythinkerMascot class="hero-mascot" :width="164" :height="205" />
         <h1>Pythinker Code</h1>
         <p class="hero-accent">Think first, then code.</p>
-        <p class="hero-lead">An open-source AI engineering agent for your terminal. It reads your repo, edits files, runs commands, and iterates until the job is done.</p>
-        <a
-          class="hero-npm-badge"
-          href="https://www.npmjs.com/package/@pymodel/pythinker-code"
-          target="_blank"
-          rel="noopener"
-        >
-          <img
-            src="https://img.shields.io/npm/dm/%40pymodel%2Fpythinker-code?style=flat&logo=npm&logoColor=white&color=2b89ff&label=downloads"
-            alt="npm downloads per month for @pymodel/pythinker-code"
-            width="161"
-            height="20"
-            loading="lazy"
-          />
-        </a>
+        <p class="hero-lead">Pythinker Code is an open-source AI engineering agent. It reads your repo, edits files, runs commands, and iterates until the job is done — in a native desktop app, your terminal, or VS Code.</p>
+        <div class="hero-download">
+          <div class="hero-download-actions">
+            <a
+              v-for="(download, index) in desktopDownloads"
+              :key="download.id"
+              :class="index === 0 ? 'button button-primary' : 'button button-secondary'"
+              :href="download.href"
+              target="_blank"
+              rel="noopener"
+            >
+              <img :src="download.icon" alt="" width="18" height="18" />
+              {{ download.label }}
+            </a>
+          </div>
+          <p class="hero-download-note">
+            {{ desktopDownloads.map((download) => download.note).join(' · ') }} ·
+            <a :href="DESKTOP_RELEASE_URL" target="_blank" rel="noopener">All downloads</a>
+          </p>
+        </div>
+        <p class="hero-install-label">Or install the CLI</p>
         <div class="hero-install">
           <InstallCommand />
         </div>
-        <div class="hero-download-milestone">
-          <LegacyDownloadsPopup />
-        </div>
         <p class="hero-caption">Free and open source. MIT licensed. macOS, Linux, and Windows.</p>
       </div>
     </header>
@@ -270,8 +298,8 @@ onUnmounted(() => {
         <h2 id="desktop-title" class="display-md">Pythinker Desktop</h2>
         <p class="desktop-showcase-lead">The agent in a native macOS app, with sidebar sessions, live activity, and auto-updates.</p>
         <div class="desktop-showcase-actions">
-          <a class="button button-primary" href="https://github.com/PyModel/pythinker-code/releases/latest" target="_blank" rel="noopener">Download for macOS</a>
-          <span class="desktop-showcase-note">Auto-updates included · Apple Silicon</span>
+          <a class="button button-primary" :href="desktopDownloads[0].href" target="_blank" rel="noopener">{{ desktopDownloads[0].label }}</a>
+          <span class="desktop-showcase-note">Auto-updates included · macOS (Apple Silicon) and Windows (x64)</span>
         </div>
       </div>
     </section>
@@ -511,6 +539,10 @@ onUnmounted(() => {
         </div>
       </div>
     </section>
+
+    <div class="container milestone-footnote">
+      <LegacyDownloadsPopup />
+    </div>
   </main>
 
   <footer class="site-footer">
@@ -708,43 +740,58 @@ onUnmounted(() => {
   line-height: 1.5;
 }
 
-.hero-install {
-  max-width: 720px;
-  margin: 10px auto 0;
+.hero-download {
+  margin-top: 24px;
 }
 
-.hero-download-milestone {
+.hero-download-actions {
   display: flex;
-  margin-top: 14px;
+  flex-wrap: wrap;
   justify-content: center;
+  gap: 10px;
 }
 
-.hero-npm-badge {
-  display: inline-flex;
-  margin-top: 14px;
-  border-radius: var(--radius);
-  opacity: 0.85;
-  transition: opacity 0.2s ease;
+.hero-download-actions .button {
+  gap: 8px;
 }
 
-.hero-npm-badge:hover {
-  opacity: 1;
+.hero-download-actions img {
+  width: 18px;
+  height: 18px;
+  flex: 0 0 18px;
 }
 
-/* ponytail: width:auto lets the badge grow as the download count does; the width attr only reserves space */
-.hero-npm-badge img {
-  display: block;
-  width: auto;
-  height: 20px;
+.hero-download-note {
+  margin-top: 10px;
+}
+
+.hero-install-label {
+  margin-top: 20px;
 }
 
+.hero-install {
+  max-width: 720px;
+  margin: 8px auto 0;
+}
+
+.milestone-footnote {
+  display: flex;
+  margin-block: 48px;
+  justify-content: center;
+}
+
+.hero-download-note,
+.hero-install-label,
 .hero-caption {
-  margin-top: 12px;
   color: var(--ink-subtle);
   font-size: 13px;
   line-height: 1.38;
 }
 
+.hero-caption {
+  margin-top: 12px;
+}
+
 .hero-mascot {
   display: block;
   width: clamp(128px, 12vw, 164px);
diff --git a/apps/site/src/components/ParticleField.vue b/apps/site/src/components/ParticleField.vue
new file mode 100644
index 00000000..36d12fe6
--- /dev/null
+++ b/apps/site/src/components/ParticleField.vue
@@ -0,0 +1,156 @@
+<script setup>
+import { nextTick, onMounted, onUnmounted, ref } from 'vue';
+
+const canvas = ref(null);
+const enabled = ref(false);
+
+let context;
+let animationFrame;
+let particles = [];
+let viewportWidth = 0;
+let viewportHeight = 0;
+let mounted = false;
+
+const pointer = { x: Infinity, y: Infinity };
+const pointerRadius = 120;
+
+function createParticles() {
+  const count = Math.max(40, Math.min(90, Math.round((viewportWidth * viewportHeight) / 16000)));
+  particles = Array.from({ length: count }, () => {
+    const homeX = Math.random() * viewportWidth;
+    const homeY = Math.random() * viewportHeight;
+    return {
+      homeX,
+      homeY,
+      x: homeX,
+      y: homeY,
+      velocityX: 0,
+      velocityY: 0,
+      driftX: (Math.random() - 0.5) * 0.08,
+      driftY: (Math.random() - 0.5) * 0.08,
+      radius: 0.8 + Math.random(),
+      color: Math.random() < 0.06 ? 'rgba(43, 137, 255, 0.35)' : 'rgba(17, 17, 19, 0.22)',
+    };
+  });
+}
+
+function resize() {
+  viewportWidth = window.innerWidth;
+  viewportHeight = window.innerHeight;
+  const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
+
+  context.setTransform(1, 0, 0, 1, 0, 0);
+  canvas.value.width = Math.round(viewportWidth * pixelRatio);
+  canvas.value.height = Math.round(viewportHeight * pixelRatio);
+  context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+  createParticles();
+}
+
+function moveParticles() {
+  for (const particle of particles) {
+    particle.homeX += particle.driftX;
+    particle.homeY += particle.driftY;
+    if (particle.homeX < 0 || particle.homeX > viewportWidth) particle.driftX *= -1;
+    if (particle.homeY < 0 || particle.homeY > viewportHeight) particle.driftY *= -1;
+
+    const deltaX = particle.x - pointer.x;
+    const deltaY = particle.y - pointer.y;
+    const distance = Math.hypot(deltaX, deltaY);
+
+    if (distance < pointerRadius) {
+      const force = ((pointerRadius - distance) / pointerRadius) * 0.8;
+      const safeDistance = Math.max(distance, 0.01);
+      particle.velocityX += (deltaX / safeDistance) * force;
+      particle.velocityY += (deltaY / safeDistance) * force;
+    } else {
+      particle.velocityX += (particle.homeX - particle.x) * 0.008;
+      particle.velocityY += (particle.homeY - particle.y) * 0.008;
+    }
+
+    particle.velocityX *= 0.92;
+    particle.velocityY *= 0.92;
+    particle.x += particle.velocityX;
+    particle.y += particle.velocityY;
+  }
+}
+
+function drawParticles() {
+  context.clearRect(0, 0, viewportWidth, viewportHeight);
+  moveParticles();
+
+  for (const particle of particles) {
+    context.beginPath();
+    context.arc(particle.x, particle.y, particle.radius, 0, Math.PI * 2);
+    context.fillStyle = particle.color;
+    context.fill();
+  }
+}
+
+function animate() {
+  drawParticles();
+  animationFrame = window.requestAnimationFrame(animate);
+}
+
+function startAnimation() {
+  if (animationFrame !== undefined || document.hidden) return;
+  animationFrame = window.requestAnimationFrame(animate);
+}
+
+function stopAnimation() {
+  if (animationFrame === undefined) return;
+  window.cancelAnimationFrame(animationFrame);
+  animationFrame = undefined;
+}
+
+function onPointerMove(event) {
+  pointer.x = event.clientX;
+  pointer.y = event.clientY;
+}
+
+function onVisibilityChange() {
+  if (document.hidden) stopAnimation();
+  else startAnimation();
+}
+
+onMounted(async () => {
+  mounted = true;
+  if (
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+    || !window.matchMedia('(pointer: fine)').matches
+  ) return;
+
+  enabled.value = true;
+  await nextTick();
+  if (!mounted) return;
+
+  context = canvas.value?.getContext('2d');
+  if (!context) return;
+
+  resize();
+  window.addEventListener('pointermove', onPointerMove, { passive: true });
+  window.addEventListener('resize', resize);
+  document.addEventListener('visibilitychange', onVisibilityChange);
+  startAnimation();
+});
+
+onUnmounted(() => {
+  mounted = false;
+  stopAnimation();
+  window.removeEventListener('pointermove', onPointerMove);
+  window.removeEventListener('resize', resize);
+  document.removeEventListener('visibilitychange', onVisibilityChange);
+});
+</script>
+
+<template>
+  <canvas v-if="enabled" ref="canvas" class="particle-field" aria-hidden="true"></canvas>
+</template>
+
+<style scoped>
+.particle-field {
+  position: fixed;
+  z-index: -1;
+  inset: 0;
+  pointer-events: none;
+}
+</style>

From b3039cc0eed93cd95a08e2925efd0110899ae3a2 Mon Sep 17 00:00:00 2001
From: elkaix <melkholy@techmatrix.com>
Date: Sun, 16 Aug 2026 05:15:37 -0400
Subject: [PATCH 4/4] docs(changeset): describe the 30-minute question lease
 accurately

---
 .changeset/question-lease-and-labels.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/question-lease-and-labels.md b/.changeset/question-lease-and-labels.md
index a5dd49e0..85d88046 100644
--- a/.changeset/question-lease-and-labels.md
+++ b/.changeset/question-lease-and-labels.md
@@ -1,5 +1,5 @@
 ---
-'@pymodel/pythinker-code': patch
+'@pymodel/pythinker-code': minor
 ---
 
-Questions no longer expire after 60 seconds, expired questions are not reported as user dismissals, answers retain question text and option labels, and Escape no longer dismisses a question.
+Questions now stay open for 30 minutes instead of 60 seconds, and the card warns when the lease is close to its end. An expired question is no longer reported to the agent as a user dismissal, answers carry the question text and the option labels the user saw instead of internal ids, Escape no longer dismisses an open question, and a question that cannot be delivered now fails as a tool error instead of a silent dismissal.