@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/injected-env.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { INJECTED_ENV_KEY, assignInjectedEnv, injectedEnvKeys } from './injected-env.js';
+
+describe('assignInjectedEnv', () => {
+  it('sets the values and records their names', () => {
+    const env = { PATH: '/usr/bin' };
+
+    expect(assignInjectedEnv(env, { OPENCHAMBER_RUNTIME: 'desktop', OPENCHAMBER_DESKTOP_NOTIFY: 'true' })).toBe(env);
+
+    expect(env).toEqual({
+      PATH: '/usr/bin',
+      OPENCHAMBER_RUNTIME: 'desktop',
+      OPENCHAMBER_DESKTOP_NOTIFY: 'true',
+      [INJECTED_ENV_KEY]: 'OPENCHAMBER_RUNTIME,OPENCHAMBER_DESKTOP_NOTIFY',
+    });
+    expect(injectedEnvKeys(env)).toEqual(new Set(['OPENCHAMBER_RUNTIME', 'OPENCHAMBER_DESKTOP_NOTIFY', INJECTED_ENV_KEY]));
+  });
+
+  it('leaves a value the shell already had as the user\'s', () => {
+    const env = { OPENCODE_PASSWORD: 'theirs', OPENCHAMBER_SKIP_API_COMPRESSION: 'false' };
+
+    assignInjectedEnv(env, {
+      OPENCODE_PASSWORD: 'theirs',
+      OPENCODE_SERVER_PASSWORD: 'theirs',
+      OPENCHAMBER_SKIP_API_COMPRESSION: env.OPENCHAMBER_SKIP_API_COMPRESSION || 'true',
+    });
+
+    expect(env.OPENCHAMBER_SKIP_API_COMPRESSION).toBe('false');
+    expect(injectedEnvKeys(env)).toEqual(new Set(['OPENCODE_SERVER_PASSWORD', INJECTED_ENV_KEY]));
+  });
+
+  it('adds to a record inherited from the parent process', () => {
+    const env = assignInjectedEnv({}, { OPENCHAMBER_RUNTIME: 'desktop' });
+    const child = assignInjectedEnv({ ...env }, { OPENCODE_CONFIG: '/tmp/opencode.json', OPENCHAMBER_RUNTIME: 'desktop' });
+
+    expect(child[INJECTED_ENV_KEY]).toBe('OPENCHAMBER_RUNTIME,OPENCODE_CONFIG');
+    expect(env[INJECTED_ENV_KEY]).toBe('OPENCHAMBER_RUNTIME');
+  });
+
+  it('skips undefined values and writes no record when nothing changed', () => {
+    const env = { OPENCHAMBER_HOST: '0.0.0.0' };
+
+    assignInjectedEnv(env, { OPENCHAMBER_UI_PASSWORD: undefined, OPENCHAMBER_HOST: '0.0.0.0' });
+
+    expect(env).toEqual({ OPENCHAMBER_HOST: '0.0.0.0' });
+    expect(injectedEnvKeys(env).size).toBe(0);
+  });
+});
+
+describe('injectedEnvKeys', () => {
+  it('ignores a malformed record', () => {
+    expect(injectedEnvKeys({ [INJECTED_ENV_KEY]: '' }).size).toBe(0);
+    expect(injectedEnvKeys({ [INJECTED_ENV_KEY]: ',,' })).toEqual(new Set([INJECTED_ENV_KEY]));
+  });
+});

package/server/lib/linear/DOCUMENTATION.md

@@ -13,7 +13,7 @@ VS Code omits Linear (`RuntimeAPIs.linear` is optional). Hide Linear UI when the
 - `packages/web/server/lib/linear/auth.js`: auth file, client id, scopes, redirect URI.
 - `packages/web/server/lib/linear/oauth.js`: authorization-code + PKCE S256, public callback broker handoff, refresh, revoke.
 - `packages/web/server/lib/linear/client.js`: GraphQL helper, viewer/organization lookup, and access-token refresh. GraphQL errors prefer `extensions.userPresentableMessage` / validation constraints over the generic `Argument Validation Error` label. User-facing Linear errors set `LinearApiError.userError`. Requests send `public-file-urls-expire-in: 3600` so file URLs in issue descriptions and comments are temporarily readable in the panel.
-- `packages/web/server/lib/linear/issues.js`: list/search/get issues, team workflow states, `issueUpdate`, and `commentCreate`. Parses identifiers and Linear URLs. `issueUpdate` resolves identifiers to UUIDs first because Linear's mutation does not accept `ENG-12`. List/get include `state.id`, `priority` (0–4), and labels (`id`, `name`, sanitized hex `color`) so the panel can show them and update status.
+- `packages/web/server/lib/linear/issues.js`: list/search/get issues, team workflow states, `issueUpdate`, and `commentCreate`. Parses identifiers and Linear URLs. `issueUpdate` resolves identifiers to UUIDs first because Linear's mutation does not accept `ENG-12`. List/get include `state.id`, `priority` (0–4), and labels (`id`, `name`, sanitized hex `color`) so the panel can show them and update status. Every issue also carries `parent` (the issue's own fields without labels) and `subIssueProgress` (`{ total, done, more }`, done counts completed, canceled and duplicate states, null without sub-issues). Linear has no sub-issue count and every connection multiplies a query's complexity by its page size (one query may not exceed 10,000 points), so a list asks only the first 20 sub-issue states per issue; `more` says there are others. Get and update add `subIssues` (first 100, related-issue fields, in Linear's `subIssueSortOrder`) and `subIssuesMore`.
 - `packages/web/server/lib/linear/teams.js`: list Linear teams for mapping UI.
 - `packages/web/server/lib/linear/mapping.js`: persist default and per-team OpenChamber project paths. Separate from the auth file so disconnect does not wipe maps.
 - `packages/web/server/lib/linear/status.js`: persist per-session started/completed/failure flags and post the matching Linear comment with an open-session URL. Posts nothing unless the user opted in and the session origin is public; `isPublicSessionOrigin` rejects loopback, private LAN, carrier-grade NAT, link-local and single-label hosts. The dedupe file keeps the newest 500 sessions.
@@ -78,12 +78,11 @@ A worktree started from the panel or picker is created in that mapped project. N
 
 - `RuntimeAPIs.linear` is optional. Hide Linear settings, the chat picker, and the panel when it is missing (VS Code).
 - Store: `packages/ui/src/stores/useLinearAuthStore.ts`. App start refreshes it from `App.tsx` and `MobileApp.tsx`, not `VSCodeApp`.
-- Settings: first-party section on the Integrations page. Connect opens the authorization URL and polls status until the workspace list or current `authorizedAt` changes, so Add workspace is not treated as done just because a workspace was already connected. When connected, map a default project and optional per-team projects for the current workspace. Other stored workspaces appear in a list with Switch to. Disconnect removes the current workspace only. The panel can also switch the current workspace when more than one is stored.
-- Context panel: desktop/web right-hand rail surface `linear` (`packages/ui/src/components/views/LinearIssuesView.tsx`). Singleton like git/pr. The rail icon is hidden until a Linear workspace is connected; disconnecting while the panel is open closes it. List/search defaults to all issues; the status filter is All, Backlog, To Do, In Progress, In Review, Done, Canceled, and Duplicate, matching the card status order. Identifier/URL still finds completed. Status, assignee, team, and priority filters persist in `useUIStore` so they survive rail switches. Non-default list filters and search tint the filter icon `text-primary`, same as the context rail; one control clears them, not the workspace switch. Changing those filters keeps the previous list until the next page arrives and does not disable the filter row. On a narrow panel search and the filters other than status drop to icons; status keeps its label. The card shows priority and labels. Comments render as an avatar timeline matching the pull request panel, so both context surfaces read alike; comment authors carry `avatarUrl`. The card is read-only except status (`issueUpdate`) and Close (first completed workflow state). Start session stays in a footer while the description and comments scroll. Start session / worktree share `startLinearIssueSession` with the picker. No create-issue, no writing comments, no polling. VS Code and the mobile workspace drawer omit this rail.
-- Chat: composer attach menu "Link Linear Issue" attaches body and comments as `linear-issue` context on the next send. Exclusive with a linked GitHub issue or PR. The attached issue is stored on session metadata (`kind: 'linear'`) so work status can show it. Clicking that work-status row opens the Linear rail when Linear is connected on desktop/web; otherwise the Linear URL. Managed Chats do not offer start-from-issue; those sessions have no project directory.
+- Settings: first-party section on the Integrations page. Connect opens the authorization URL and polls status until the workspace list or current `authorizedAt` changes, so Add workspace is not treated as done just because a workspace was already connected. When connected, map a default project and optional per-team projects for the current workspace. Other stored workspaces appear in a list with Switch to. Disconnect removes the current workspace only. The board can also switch the current workspace when more than one is stored.
+- Board: Linear issues list on the issues and PRs board (`packages/ui/src/components/sourceBoard`, desktop/web), next to the repository's issues and PRs. It filters by team, state, whose issues (`assignee=me` or `created`) and priority together, changes an issue's state from its state pill (`issueUpdate`), switches the workspace from the team menu, and starts a session or worktree with the issue attached to the message box. The team's mapped project is where the session starts unless the user picks another. VS Code and the phone shell have their own surfaces (the phone shell opens the board from the sessions menu).
+- Chat: composer attach menu "Link Linear Issue" attaches body and comments as `linear-issue` context on the next send. Exclusive with a linked GitHub issue or PR. The attached issue is stored on session metadata (`kind: 'linear'`) so work status can show it. Clicking that work-status row opens the board searched for the issue when Linear is connected on desktop/web; otherwise the Linear URL. Managed Chats do not offer start-from-issue; those sessions have no project directory.
 - Worktree: New Worktree can start from a Linear issue. It uses the currently active project and does not consult team-to-project mapping. It shares the reference picker with GitHub (single choice); one issue, PR or Linear issue names the branch.
-- Status comments: off until the user turns them on in Settings -> Integrations -> Linear (`LinearSessionComments.tsx`). When on, create-session and worktree-from-Linear post `started` after the session exists. The event hub posts `completed` on the first idle after that, and `failure` on `session.error` except `MessageAbortedError`. Failed comments must not fail session create. Comment bodies are English (they live on Linear) and are one markdown link named `OpenChamber session started` (or completed/failed). Web uses `/?session=<id>` on the current origin; desktop reports the loopback origin its own server listens on, not `openchamber-ui://`. A Linear comment is read by the whole team, so the server posts nothing when that origin is not publicly reachable rather than publishing a link only its author could open. Opening `/?session=` selects that session after the global session list can resolve its directory.
-- Magic prompts: `linear.issue.review.visible` / `.instructions`, used only by Start session from the panel and the chat. An issue attached in the composer or from New Worktree carries no instructions.
+- Status comments: off until the user turns them on in Settings -> Integrations -> Linear (`LinearSessionComments.tsx`). When on, a session whose first message carries the issue posts `started` once it is sent. The event hub posts `completed` on the first idle after that, and `failure` on `session.error` except `MessageAbortedError`. Failed comments must not fail session create. Comment bodies are English (they live on Linear) and are one markdown link named `OpenChamber session started` (or completed/failed). Web uses `/?session=<id>` on the current origin; desktop reports the loopback origin its own server listens on, not `openchamber-ui://`. A Linear comment is read by the whole team, so the server posts nothing when that origin is not publicly reachable rather than publishing a link only its author could open. Opening `/?session=` selects that session after the global session list can resolve its directory.
 
 ## Notes for contributors
 

package/server/lib/linear/issues.js

@@ -25,7 +25,7 @@ function readListStatus(value) {
 
 function readListAssignee(value) {
   const assignee = readTrimmedString(value);
-  if (assignee === 'me' || assignee === 'any') {
+  if (assignee === 'me' || assignee === 'created' || assignee === 'any') {
     return assignee;
   }
   return 'any';
@@ -59,6 +59,9 @@ function buildIssueListFilter({ status, assignee, teamId, priority } = {}) {
   if (resolvedAssignee === 'me') {
     filter.assignee = { isMe: { eq: true } };
   }
+  if (resolvedAssignee === 'created') {
+    filter.creator = { isMe: { eq: true } };
+  }
   if (team) {
     filter.team = { id: { eq: team } };
   }
@@ -68,7 +71,9 @@ function buildIssueListFilter({ status, assignee, teamId, priority } = {}) {
   return Object.keys(filter).length > 0 ? filter : undefined;
 }
 
-const ISSUE_SUMMARY_FIELDS = `
+// A related issue (a parent, a sub-issue) carries what its row and its own
+// preview header need; labels stay out, they multiply the query's cost.
+const RELATED_ISSUE_FIELDS = `
   id
   identifier
   title
@@ -78,7 +83,26 @@ const ISSUE_SUMMARY_FIELDS = `
   state { id name type }
   assignee { name displayName avatarUrl }
   team { id key name }
+`;
+// Linear has no sub-issue count, and every connection multiplies the query's
+// complexity by its page size (a query may not exceed 10,000 points). A list
+// page asks this many sub-issue states per issue; more reads as "N+".
+const SUB_ISSUE_COUNT_LIMIT = 20;
+const SUB_ISSUE_PAGE = 100;
+const ISSUE_SUMMARY_FIELDS = `
+  ${RELATED_ISSUE_FIELDS}
   labels { nodes { id name color } }
+  parent { ${RELATED_ISSUE_FIELDS} }
+  children(first: ${SUB_ISSUE_COUNT_LIMIT}) {
+    nodes { state { type } }
+    pageInfo { hasNextPage }
+  }
+`;
+const SUB_ISSUES_FIELDS = `
+  subIssues: children(first: ${SUB_ISSUE_PAGE}) {
+    nodes { ${RELATED_ISSUE_FIELDS} subIssueSortOrder }
+    pageInfo { hasNextPage }
+  }
 `;
 const LIST_QUERY = `
   query ListLinearIssues($first: Int!, $after: String, $filter: IssueFilter) {
@@ -100,6 +124,7 @@ const GET_QUERY = `
   query GetLinearIssue($id: String!) {
     issue(id: $id) {
       ${ISSUE_SUMMARY_FIELDS}
+      ${SUB_ISSUES_FIELDS}
       description
       comments(first: 50) {
         nodes {
@@ -135,6 +160,7 @@ const ISSUE_UPDATE = `
       success
       issue {
         ${ISSUE_SUMMARY_FIELDS}
+        ${SUB_ISSUES_FIELDS}
         description
         comments(first: 50) {
           nodes {
@@ -266,7 +292,7 @@ function readLabels(value) {
   return nodes.map(readLabel).filter(Boolean);
 }
 
-function readIssueSummary(node) {
+function readRelatedIssue(node) {
   if (!isPlainObject(node)) return null;
   const id = readTrimmedString(node.id);
   const identifier = readTrimmedString(node.identifier);
@@ -282,11 +308,41 @@ function readIssueSummary(node) {
     assignee: readAssignee(node.assignee),
     team: readTeam(node.team),
     priority: readPriority(node.priority),
-    labels: readLabels(node.labels),
     updatedAt: readTrimmedString(node.updatedAt) || null,
   };
 }
 
+const FINISHED_STATE_TYPES = new Set(['completed', 'canceled', 'duplicate']);
+
+/** How many sub-issues an issue has and how many are finished; null without any. */
+function readSubIssueProgress(connection) {
+  const nodes = isPlainObject(connection) && Array.isArray(connection.nodes) ? connection.nodes : [];
+  if (nodes.length === 0) return null;
+  const done = nodes.filter((node) => FINISHED_STATE_TYPES.has(readState(node?.state)?.type)).length;
+  return { total: nodes.length, done, more: readPageInfo(connection).hasMore };
+}
+
+function readIssueSummary(node) {
+  const summary = readRelatedIssue(node);
+  if (!summary) return null;
+  return {
+    ...summary,
+    labels: readLabels(node.labels),
+    parent: readRelatedIssue(node.parent),
+    subIssueProgress: readSubIssueProgress(node.children),
+  };
+}
+
+// Linear's own order: the one the sub-issues are dragged into in Linear.
+function readSubIssues(connection) {
+  const nodes = isPlainObject(connection) && Array.isArray(connection.nodes) ? connection.nodes : [];
+  return nodes
+    .map((node) => ({ issue: readRelatedIssue(node), order: readFiniteNumber(node?.subIssueSortOrder) ?? 0 }))
+    .filter((entry) => entry.issue)
+    .sort((left, right) => left.order - right.order)
+    .map((entry) => entry.issue);
+}
+
 function readComment(node) {
   if (!isPlainObject(node)) return null;
   const id = readTrimmedString(node.id);
@@ -318,6 +374,8 @@ function readIssue(node) {
     ...summary,
     description: isString(node.description) ? node.description : null,
     comments,
+    subIssues: readSubIssues(node.subIssues),
+    subIssuesMore: readPageInfo(node.subIssues).hasMore,
   };
 }
 

package/server/lib/linear/issues.test.js

@@ -157,6 +157,8 @@ describe('Linear issue list/get', () => {
         priority: 1,
         labels: [{ id: 'label-bug', name: 'Bug', color: '#eb5757' }],
         updatedAt: '2026-09-30T10:00:00.000Z',
+        parent: null,
+        subIssueProgress: null,
       }],
       cursor: 'cursor-2',
       hasMore: true,
@@ -263,6 +265,18 @@ describe('Linear issue list/get', () => {
     expect(result.issues).toHaveLength(1);
   });
 
+  it('lists the issues I created', async () => {
+    vi.stubGlobal('fetch', vi.fn(async (_url, options) => {
+      expect(JSON.parse(options.body).variables.filter).toEqual({
+        state: { type: { nin: ['completed', 'canceled', 'duplicate'] } },
+        creator: { isMe: { eq: true } },
+      });
+      return jsonResponse({ data: { issues: { nodes: [issueNode], pageInfo: { hasNextPage: false, endCursor: null } } } });
+    }));
+    const result = await listLinearIssues({ assignee: 'created' });
+    expect(result.issues).toHaveLength(1);
+  });
+
   it('filters each panel status to a Linear state type or name', async () => {
     const filters = [];
     vi.stubGlobal('fetch', vi.fn(async (_url, options) => {
@@ -374,6 +388,60 @@ describe('Linear issue list/get', () => {
     }]);
   });
 
+  it('reads the parent and how many sub-issues a listed issue has finished', async () => {
+    const child = (type) => ({ state: { type } });
+    vi.stubGlobal('fetch', vi.fn(async (_url, options) => {
+      const body = JSON.parse(options.body);
+      expect(body.query).toContain('children(first: 20)');
+      return jsonResponse({
+        data: {
+          issues: {
+            nodes: [
+              {
+                ...issueNode,
+                parent: { id: 'issue-uuid-0', identifier: 'ENG-1', title: 'Login revamp', url: 'https://linear.app/openchamber/issue/ENG-1', state: { type: 'started' } },
+                children: { nodes: [child('completed'), child('canceled'), child('started')], pageInfo: { hasNextPage: true } },
+              },
+              { ...issueNode, id: 'issue-uuid-2', identifier: 'ENG-13', parent: null, children: { nodes: [], pageInfo: { hasNextPage: false } } },
+            ],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      });
+    }));
+
+    const result = await listLinearIssues();
+    expect(result.issues?.[0]?.parent).toMatchObject({ id: 'issue-uuid-0', identifier: 'ENG-1', title: 'Login revamp' });
+    expect(result.issues?.[0]?.parent?.labels).toBeUndefined();
+    expect(result.issues?.[0]?.subIssueProgress).toEqual({ total: 3, done: 2, more: true });
+    expect(result.issues?.[1]?.parent).toBeNull();
+    expect(result.issues?.[1]?.subIssueProgress).toBeNull();
+  });
+
+  it('loads one issue with its sub-issues in Linear order', async () => {
+    const sub = (identifier, order) => ({
+      id: `uuid-${identifier}`,
+      identifier,
+      title: `Part ${identifier}`,
+      url: `https://linear.app/openchamber/issue/${identifier}`,
+      state: { id: 's', name: 'Todo', type: 'unstarted' },
+      subIssueSortOrder: order,
+    });
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      data: {
+        issue: {
+          ...issueNode,
+          subIssues: { nodes: [sub('ENG-21', 2), sub('ENG-20', -1), { id: '', identifier: 'X' }], pageInfo: { hasNextPage: false } },
+          comments: { nodes: [] },
+        },
+      },
+    })));
+
+    const result = await getLinearIssue('ENG-12');
+    expect(result.issue?.subIssues?.map((issue) => issue.identifier)).toEqual(['ENG-20', 'ENG-21']);
+    expect(result.issue?.subIssuesMore).toBe(false);
+  });
+
   it('creates a comment on the resolved issue UUID', async () => {
     vi.stubGlobal('fetch', vi.fn(async (_url, options) => {
       const body = JSON.parse(options.body);

package/server/lib/linear/oauth.js

@@ -8,10 +8,10 @@ import {
 } from './auth.js';
 import { isPlainObject, isString, readFiniteNumber, readTrimmedString } from './parse.js';
 
-export const LINEAR_AUTHORIZE_URL = 'https://linear.app/oauth/authorize';
-export const LINEAR_TOKEN_URL = 'https://api.linear.app/oauth/token';
-export const LINEAR_REVOKE_URL = 'https://api.linear.app/oauth/revoke';
-export const PENDING_AUTHORIZATION_TTL_MS = 10 * 60_000;
+const LINEAR_AUTHORIZE_URL = 'https://linear.app/oauth/authorize';
+const LINEAR_TOKEN_URL = 'https://api.linear.app/oauth/token';
+const LINEAR_REVOKE_URL = 'https://api.linear.app/oauth/revoke';
+const PENDING_AUTHORIZATION_TTL_MS = 10 * 60_000;
 
 const pendingByState = new Map();
 const brokerPollsByState = new Map();
@@ -24,7 +24,7 @@ export class LinearOAuthError extends Error {
   }
 }
 
-export function createPkcePair() {
+function createPkcePair() {
   const verifier = crypto.randomBytes(32).toString('base64url');
   const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
   return { verifier, challenge };

package/server/lib/linear/parse.js

@@ -1,13 +1,6 @@
-export function isString(value) {
-  return Object.prototype.toString.call(value) === '[object String]';
-}
+import { isString } from '../shared/guards.js';
 
-export function isPlainObject(value) {
-  if (value == null || Array.isArray(value)) {
-    return false;
-  }
-  return Object.getPrototypeOf(value) === Object.prototype;
-}
+export { isString, isPlainObject } from '../shared/guards.js';
 
 export function readTrimmedString(value) {
   return isString(value) && value.trim() ? value.trim() : '';

package/server/lib/message-queue/DOCUMENTATION.md

@@ -71,7 +71,29 @@ never replaces editable text or delivered parts. Older items without a summary
 derive one from the attached comment metadata or the first non-instruction
 context text. This optional field needs no queue-file migration.
 
-## Persistence
+## Scheduled items
+
+Scheduled tasks use the same items with an optional `scheduledTask` field
+containing `projectId` and `taskId`. Reuse does not change the target's goal or
+auto-accept policy.
+Only the server can enqueue this provenance. Enqueue deduplicates the project
+and task across all session queues. A scheduled item can omit its model to
+keep the target session selection. Normal composer items still require their
+captured model. The UI retains both kinds in the same projection.
+
+Scheduled send guards and terminal result callbacks apply only to scheduled
+items. A definitive before-send target or task refusal with 404 or 409 removes
+that item and lets the next item proceed. This includes removed or retargeted
+tasks and moved targets. Other validation errors and all send failures use the
+existing queue retry policy, including model-switch 404 or 409 responses.
+Successful send reports `sent` without waiting for an assistant reply. Removing,
+clearing or evicting a waiting scheduled item reports `cancelled`. Scheduled
+items can be reordered and removed, but cannot be taken for editing or manual
+send. Bulk take returns only ordinary items and leaves scheduled items queued.
+Disable, delete and retarget use `cancelScheduledTask`. Existing composer
+persistence, retries, directory query and delivery gates remain unchanged.
+
+## Queue file
 
 `<data-dir>/message-queue.json` (`OPENCHAMBER_DATA_DIR` or
 `~/.config/openchamber`): `{ version, revision, sessions: { [sessionId]:

package/server/lib/message-queue/runtime.js

@@ -133,7 +133,11 @@ export const parseQueuedItemInput = (value) => {
     throw new TypeError('item needs text, attachments, or context');
   }
   const sendConfig = parseSendConfig(raw.sendConfig);
-  if (!sendConfig) throw new TypeError('item sendConfig with providerID and modelID is required');
+  const provenance = asRecord(raw.scheduledTask);
+  const projectId = asNonEmptyString(provenance?.projectId);
+  const taskId = asNonEmptyString(provenance?.taskId);
+  if (provenance && (!projectId || !taskId)) throw new TypeError('invalid scheduledTask provenance');
+  if (!sendConfig && !provenance) throw new TypeError('item sendConfig with providerID and modelID is required');
   const item = { content, text };
   const agentMention = asNonEmptyString(raw.agentMention);
   if (agentMention) item.agentMention = agentMention;
@@ -141,7 +145,12 @@ export const parseQueuedItemInput = (value) => {
   item.context = context;
   const contextPreview = asNonEmptyString(raw.contextPreview).slice(0, 103);
   if (contextPreview) item.contextPreview = contextPreview;
-  item.sendConfig = sendConfig;
+  item.sendConfig = sendConfig ?? {};
+  if (provenance) {
+    item.scheduledTask = { projectId, taskId };
+    const agent = asNonEmptyString(raw.sendConfig?.agent);
+    if (agent) item.sendConfig.agent = agent;
+  }
   return item;
 };
 
@@ -177,6 +186,7 @@ const toPublicItem = (item) => {
       + (contextPreview.length > firstLine.length || firstLine.length > 100 ? '...' : '');
   }
   publicItem.sendConfig = { ...item.sendConfig };
+  if (item.scheduledTask) publicItem.scheduledTask = { ...item.scheduledTask };
   return publicItem;
 };
 
@@ -228,6 +238,9 @@ export function createMessageQueueRuntime({
   sessionKnowledgeRuntime = null,
   broadcastGlobalUiEvent,
   onPromptSent,
+  beforeScheduledTaskSend,
+  validateScheduledTaskTarget,
+  onScheduledTaskResult,
   // Resolves the `openchamber/auto` sentinel into a real model and agent right
   // before the send; absent means the queue never sees the sentinel.
   resolveAutoSelection = null,
@@ -373,7 +386,16 @@ export function createMessageQueueRuntime({
     return { revision, session: sessionSnapshot(sessionId) };
   };
 
-  const setQueueItems = (sessionId, directory, items) => {
+  const reportScheduledResult = (item, status, error) => {
+    if (!item.scheduledTask) return;
+    Promise.resolve().then(() => onScheduledTaskResult?.(item.scheduledTask, status, error))
+      .catch((failure) => console.warn('[message-queue] scheduled task state write failed:', failure?.message ?? failure));
+  };
+
+  const setQueueItems = (sessionId, directory, items, status = 'cancelled', error) => {
+    for (const item of queues.get(sessionId)?.items ?? []) {
+      if (item.scheduledTask && !items.some((entry) => entry.id === item.id)) reportScheduledResult(item, status, error);
+    }
     directories.set(sessionId, directory);
     if (items.length === 0) {
       queues.delete(sessionId);
@@ -494,13 +516,13 @@ export function createMessageQueueRuntime({
 
     // Jev routing, when the queued send named the Auto sentinel. A failure
     // inside resolves to the fallback model; only a missing fallback throws.
-    const routed = await resolveAutoSelection?.({
+    const routed = providerID && modelID ? await resolveAutoSelection?.({
       sessionId,
       directory,
       model,
       agent,
       requestText: item.text,
-    });
+    }) : null;
     if (routed) {
       model = routed.model;
       agent = routed.agent ?? agent;
@@ -508,7 +530,7 @@ export function createMessageQueueRuntime({
 
     // v2 selects model and agent on the session, not per prompt: the choice is
     // switched once and then persists.
-    await openCodeFetch(`/api/session/${encodeURIComponent(sessionId)}/model`, {
+    if (!item.scheduledTask || (providerID && modelID)) await openCodeFetch(`/api/session/${encodeURIComponent(sessionId)}/model`, {
       directory,
       method: 'POST',
       body: { model },
@@ -627,6 +649,19 @@ export function createMessageQueueRuntime({
 
     const idle = await isSessionIdle(sessionId, queue.directory);
     if (idle === null) {
+      if (head.scheduledTask && validateScheduledTaskTarget) {
+        try {
+          await validateScheduledTaskTarget(head.scheduledTask.projectId, sessionId);
+        } catch (error) {
+          if (error?.statusCode === 404 || error?.statusCode === 409) {
+            const after = queues.get(sessionId);
+            if (after) setQueueItems(sessionId, after.directory, after.items.filter((entry) => entry.id !== head.id), 'failed', error.message);
+            commit(sessionId);
+            armDispatch(sessionId);
+            return;
+          }
+        }
+      }
       armDispatch(sessionId, retryDelayMs(1));
       return;
     }
@@ -651,9 +686,23 @@ export function createMessageQueueRuntime({
     sending.set(sessionId, item.id);
     broadcast(sessionId);
     try {
+      if (item.scheduledTask) {
+        try {
+          await beforeScheduledTaskSend?.(sessionId, current.directory, item);
+        } catch (error) {
+          if (error?.statusCode !== 404 && error?.statusCode !== 409) throw error;
+          sending.delete(sessionId);
+          const after = queues.get(sessionId);
+          if (after) setQueueItems(sessionId, after.directory, after.items.filter((entry) => entry.id !== item.id), 'failed', error.message);
+          failures.delete(sessionId);
+          commit(sessionId);
+          armDispatch(sessionId);
+          return;
+        }
+      }
       await sendItem(sessionId, current.directory, item);
       const after = queues.get(sessionId);
-      if (after) setQueueItems(sessionId, after.directory, after.items.filter((entry) => entry.id !== item.id));
+      if (after) setQueueItems(sessionId, after.directory, after.items.filter((entry) => entry.id !== item.id), 'sent');
       failures.delete(sessionId);
       sending.delete(sessionId);
       commit(sessionId);
@@ -693,6 +742,16 @@ export function createMessageQueueRuntime({
     if (!directory) throw new TypeError('directory is required');
     const parsed = parseQueuedItemInput(itemInput);
     await load();
+    if (parsed.scheduledTask) {
+      for (const queue of queues.values()) {
+        if (queue.items.some((entry) => entry.scheduledTask?.projectId === parsed.scheduledTask.projectId && entry.scheduledTask.taskId === parsed.scheduledTask.taskId)) {
+          throw httpError('task is already queued', 409);
+        }
+      }
+      if ((queues.get(sessionId)?.items.length ?? 0) >= MAX_ITEMS_PER_SESSION || (!queues.has(sessionId) && queues.size >= MAX_SESSIONS)) {
+        throw httpError('message queue is full', 409);
+      }
+    }
     const item = {
       id: `queued-${now()}-${Math.random().toString(36).slice(2, 9)}`,
       createdAt: now(),
@@ -700,7 +759,7 @@ export function createMessageQueueRuntime({
     };
     const existing = queues.get(sessionId);
     const items = [...(existing?.items ?? []), item].slice(-MAX_ITEMS_PER_SESSION);
-    queues.set(sessionId, { directory, items });
+    setQueueItems(sessionId, directory, items);
     directories.set(sessionId, directory);
     if (queues.size > MAX_SESSIONS) {
       const oldest = Array.from(queues.entries())
@@ -708,7 +767,7 @@ export function createMessageQueueRuntime({
         .sort((left, right) => (left[1].items[0]?.createdAt ?? 0) - (right[1].items[0]?.createdAt ?? 0))
         .slice(0, queues.size - MAX_SESSIONS);
       for (const [staleId] of oldest) {
-        queues.delete(staleId);
+        setQueueItems(staleId, directories.get(staleId), []);
         clearTimer(staleId);
         broadcast(staleId);
         directories.delete(staleId);
@@ -741,6 +800,7 @@ export function createMessageQueueRuntime({
     const queue = queues.get(sessionId);
     const item = queue?.items.find((entry) => entry.id === itemId);
     if (!queue || !item) throw httpError('queued message not found', 404);
+    if (item.scheduledTask) throw httpError('scheduled messages cannot be taken', 409);
     setQueueItems(sessionId, queue.directory, queue.items.filter((entry) => entry.id !== itemId));
     return { ...commit(sessionId), item };
   };
@@ -752,9 +812,9 @@ export function createMessageQueueRuntime({
     const queue = queues.get(sessionId);
     if (!queue) return { revision, session: sessionSnapshot(sessionId), items: [] };
     const sendingId = sending.get(sessionId) ?? null;
-    const items = queue.items.filter((item) => item.id !== sendingId);
+    const items = queue.items.filter((item) => item.id !== sendingId && !item.scheduledTask);
     if (items.length === 0) return { revision, session: sessionSnapshot(sessionId), items: [] };
-    setQueueItems(sessionId, queue.directory, queue.items.filter((item) => item.id === sendingId));
+    setQueueItems(sessionId, queue.directory, queue.items.filter((item) => item.id === sendingId || item.scheduledTask));
     return { ...commit(sessionId), items };
   };
 
@@ -810,7 +870,7 @@ export function createMessageQueueRuntime({
     const deletedSessionId = extractDeletedSessionId(payload);
     if (deletedSessionId) {
       if (!queues.has(deletedSessionId)) return;
-      queues.delete(deletedSessionId);
+      setQueueItems(deletedSessionId, directories.get(deletedSessionId), []);
       clearTimer(deletedSessionId);
       failures.delete(deletedSessionId);
       commit(deletedSessionId);
@@ -870,11 +930,23 @@ export function createMessageQueueRuntime({
     timers.clear();
   };
 
+  const cancelScheduledTask = async (projectId, taskId) => {
+    await load();
+    for (const [sessionId, queue] of queues) {
+      const items = queue.items.filter((item) => item.scheduledTask?.projectId !== projectId || item.scheduledTask.taskId !== taskId || sending.get(sessionId) === item.id);
+      if (items.length === queue.items.length) continue;
+      setQueueItems(sessionId, queue.directory, items);
+      commit(sessionId);
+      armDispatch(sessionId);
+    }
+  };
+
   return {
     load,
     snapshot,
     sessionSnapshot,
     enqueue,
+    cancelScheduledTask,
     remove,
     take,
     takeAll,
@@ -906,6 +978,7 @@ export function registerMessageQueueRoutes(app, runtime) {
 
   app.post('/api/message-queue/sessions/:sessionId/items', async (req, res) => {
     try {
+      if (req.body?.item?.scheduledTask) throw new TypeError('scheduledTask is server-owned');
       res.json(await runtime.enqueue(req.params.sessionId, req.body?.directory, req.body?.item));
     } catch (error) {
       respondError(res, error, 'Failed to queue message');