@dotdrelle/wiki-manager 0.6.17

package/src/core/documentIntake.js

@@ -0,0 +1,311 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, extname, isAbsolute, join, resolve } from 'node:path';
+import { callMcpTool, formatMcpToolResult } from './mcp.js';
+import { parseJsonText } from './activity.js';
+import { userManagerDir } from './env.js';
+
+const SUPPORTED_EXTENSIONS = new Set([
+  '.txt', '.md', '.markdown', '.csv', '.json', '.xml', '.yaml', '.yml', '.html', '.htm', '.rtf',
+  '.png', '.jpg', '.jpeg', '.tif', '.tiff', '.bmp', '.webp',
+  '.docx', '.pptx', '.xlsx', '.doc', '.ppt', '.xls', '.odt', '.ods', '.odp',
+  '.pdf',
+]);
+
+function agentsDataDir() {
+  const configured = process.env.AGENTS_DATA_DIR || '.agents-data';
+  return isAbsolute(configured) ? configured : resolve(userManagerDir(), configured);
+}
+
+function documentInputRoot() {
+  return resolve(agentsDataDir(), 'documents', 'input');
+}
+
+function uploadsRoot() {
+  return resolve(agentsDataDir(), 'documents', 'uploads');
+}
+
+function requireWorkspace(session) {
+  if (!session?.workspace) throw new Error('No workspace loaded. Use /use <workspace>.');
+  return session.workspace;
+}
+
+function maxUploadBytes() {
+  const value = Number(process.env.DOCUMENT_MAX_UPLOAD_BYTES || 50 * 1024 * 1024);
+  return Number.isFinite(value) && value > 0 ? value : 50 * 1024 * 1024;
+}
+
+function sanitizeFilename(filename) {
+  const name = basename(String(filename || '').trim())
+    .normalize('NFKD')
+    .replace(/[^\w.\- ]+/g, '_')
+    .replace(/\s+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^\.+/g, '')
+    .slice(0, 120);
+  return name || 'upload.bin';
+}
+
+function unquotePath(value) {
+  const text = String(value ?? '').trim();
+  if (text.length >= 2) {
+    const first = text[0];
+    const last = text.at(-1);
+    if ((first === "'" && last === "'") || (first === '"' && last === '"')) {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+function assertSupportedFile(filename, size) {
+  const ext = extname(filename).toLowerCase();
+  if (!SUPPORTED_EXTENSIONS.has(ext)) {
+    throw new Error(`Unsupported document type: ${ext || 'no extension'}`);
+  }
+  const max = maxUploadBytes();
+  if (size > max) {
+    throw new Error(`Document is too large: ${size} bytes (max ${max}).`);
+  }
+}
+
+function manifestPath(workspace) {
+  return join(uploadsRoot(), `${workspace}.jsonl`);
+}
+
+async function readManifest(workspace) {
+  const file = manifestPath(workspace);
+  if (!existsSync(file)) return [];
+  const raw = await readFile(file, 'utf8');
+  return raw
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+async function writeManifest(workspace, records) {
+  const file = manifestPath(workspace);
+  await mkdir(uploadsRoot(), { recursive: true });
+  const body = records.map((record) => JSON.stringify(record)).join('\n');
+  const tmp = `${file}.tmp.${process.pid}`;
+  await writeFile(tmp, body ? `${body}\n` : '', 'utf8');
+  await rename(tmp, file);
+}
+
+async function upsertUpload(record) {
+  const records = await readManifest(record.workspace);
+  const index = records.findIndex((item) => item.id === record.id);
+  if (index === -1) records.unshift(record);
+  else records[index] = { ...records[index], ...record };
+  await writeManifest(record.workspace, records);
+  return record;
+}
+
+async function removeExistingUploadsForFilename(workspace, filename) {
+  const records = await readManifest(workspace);
+  const removed = records.filter((item) => item.filename === filename);
+  if (removed.length === 0) return [];
+
+  const keep = records.filter((item) => item.filename !== filename);
+  for (const record of removed) {
+    for (const file of [record.storedPath, record.outputPath]) {
+      if (file) await rm(file, { force: true }).catch(() => {});
+    }
+  }
+  await writeManifest(workspace, keep);
+  return removed;
+}
+
+function documentsConverter(session) {
+  const endpoint = session?.mcp?.documents;
+  if (endpoint?.status !== 'connected') return null;
+  const hasTool = (endpoint.tools ?? []).some((tool) => tool.name === 'documents_convert_to_markdown');
+  return hasTool ? endpoint : null;
+}
+
+function publicRecord(record) {
+  return {
+    id: record.id,
+    workspace: record.workspace,
+    filename: record.filename,
+    status: record.status,
+    provider: record.provider,
+    agentPath: record.agentPath,
+    outputPath: record.outputPath,
+    method: record.method,
+    bytes: record.bytes,
+    error: record.error,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  };
+}
+
+function activityFromPayload(payload) {
+  return payload?._activity && typeof payload._activity === 'object' ? payload._activity : null;
+}
+
+export async function storeDocumentUpload(session, sourcePath) {
+  const workspace = requireWorkspace(session);
+  const absolutePath = resolve(unquotePath(sourcePath));
+  const info = await stat(absolutePath);
+  if (!info.isFile()) throw new Error(`Not a file: ${sourcePath}`);
+  const filename = sanitizeFilename(absolutePath);
+  assertSupportedFile(filename, info.size);
+
+  await removeExistingUploadsForFilename(workspace, filename);
+
+  const id = randomUUID().slice(0, 8);
+  const storedFilename = `${id}-${filename}`;
+  const workspaceInput = join(documentInputRoot(), workspace);
+  await mkdir(workspaceInput, { recursive: true });
+  const storedPath = join(workspaceInput, storedFilename);
+  await copyFile(absolutePath, storedPath);
+  const now = new Date().toISOString();
+  const record = {
+    id,
+    workspace,
+    filename,
+    originalPath: absolutePath,
+    storedPath,
+    agentPath: `/documents/input/${workspace}/${storedFilename}`,
+    status: 'stored',
+    provider: null,
+    outputPath: null,
+    method: null,
+    bytes: info.size,
+    error: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  await upsertUpload(record);
+  return record;
+}
+
+export async function convertStoredDocument(session, id, options = {}) {
+  const workspace = requireWorkspace(session);
+  const records = await readManifest(workspace);
+  const record = records.find((item) => item.id === id);
+  if (!record) throw new Error(`Unknown upload id: ${id}`);
+  if (!existsSync(record.storedPath)) throw new Error(`Stored file is missing: ${record.storedPath}`);
+  if (!documentsConverter(session)) {
+    record.status = 'stored';
+    record.provider = null;
+    record.error = 'documents MCP is not connected';
+    record.updatedAt = new Date().toISOString();
+    await upsertUpload(record);
+    return { record, converted: false };
+  }
+
+  record.status = 'converting';
+  record.provider = 'documents';
+  record.error = null;
+  record.updatedAt = new Date().toISOString();
+  await upsertUpload(record);
+
+  try {
+    const toolArgs = {
+      workspace,
+      filePath: record.agentPath,
+      outputFilename: `${record.id}-${record.filename.replace(/\.[^.]+$/, '')}.md`,
+    };
+    const result = await callMcpTool(session.mcp, 'documents', 'documents_convert_to_markdown', toolArgs);
+    const payload = parseJsonText(formatMcpToolResult(result)) ?? {};
+    if (payload.ok === false) throw new Error(payload.error || 'documents conversion failed');
+
+    const activity = activityFromPayload(payload);
+    if (activity && !activity.terminal) {
+      record.jobId = payload.jobId ?? null;
+      record.updatedAt = new Date().toISOString();
+      await upsertUpload(record);
+      return { record, converted: false, activity };
+    }
+
+    record.status = 'converted';
+    record.outputPath = payload.outputPath ?? null;
+    record.method = payload.method ?? null;
+    record.error = null;
+    record.updatedAt = new Date().toISOString();
+    await upsertUpload(record);
+    return { record, converted: true, payload, activity };
+  } catch (err) {
+    record.status = 'failed';
+    record.error = err instanceof Error ? err.message : String(err);
+    record.updatedAt = new Date().toISOString();
+    await upsertUpload(record);
+    return { record, converted: false };
+  }
+}
+
+export async function storeAndMaybeConvertDocument(session, sourcePath, options = {}) {
+  const record = await storeDocumentUpload(session, sourcePath);
+  if (!documentsConverter(session)) {
+    record.error = 'documents MCP is not connected';
+    await upsertUpload(record);
+    return { record, converted: false };
+  }
+  return convertStoredDocument(session, record.id, options);
+}
+
+export async function listDocumentUploads(session) {
+  const workspace = requireWorkspace(session);
+  return (await readManifest(workspace)).map(publicRecord);
+}
+
+export async function convertPendingDocumentUploads(session, options = {}) {
+  const workspace = requireWorkspace(session);
+  const records = await readManifest(workspace);
+  const pending = records.filter((record) => ['stored', 'failed'].includes(record.status));
+  const results = [];
+  for (const record of pending) {
+    results.push(await convertStoredDocument(session, record.id, options));
+  }
+  return results;
+}
+
+function parseAgeMs(value = '30d') {
+  const match = String(value).trim().match(/^(\d+)([dhm])$/i);
+  if (!match) throw new Error('Invalid age. Use a value like 30d, 12h, or 90m.');
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const factor = unit === 'd' ? 24 * 60 * 60 * 1000 : unit === 'h' ? 60 * 60 * 1000 : 60 * 1000;
+  return amount * factor;
+}
+
+export async function cleanDocumentUploads(session, olderThan = '30d') {
+  const workspace = requireWorkspace(session);
+  const cutoff = Date.now() - parseAgeMs(olderThan);
+  const records = await readManifest(workspace);
+  const keep = [];
+  const removed = [];
+  for (const record of records) {
+    const created = Date.parse(record.createdAt || record.updatedAt || '');
+    if (Number.isFinite(created) && created < cutoff) {
+      removed.push(record);
+      if (record.storedPath) {
+        await rm(record.storedPath, { force: true }).catch(() => {});
+      }
+    } else {
+      keep.push(record);
+    }
+  }
+  if (removed.length > 0) await writeManifest(workspace, keep);
+  return { removed, kept: keep };
+}
+
+export function formatUploadRecord(record) {
+  const lines = [
+    `${record.id}  ${record.status}  ${record.filename}`,
+    `agentPath: ${record.agentPath}`,
+  ];
+  if (record.outputPath) lines.push(`outputPath: ${record.outputPath}`);
+  if (record.method) lines.push(`method: ${record.method}`);
+  if (record.error) lines.push(`note: ${record.error}`);
+  return lines.join('\n');
+}

package/src/core/documentIntake.test.js

@@ -0,0 +1,121 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  listDocumentUploads,
+  storeAndMaybeConvertDocument,
+} from './documentIntake.js';
+
+test('document intake stores uploads without requiring documents MCP', async () => {
+  const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-'));
+  process.env.AGENTS_DATA_DIR = path.join(root, '.agents-data');
+  const source = path.join(root, 'rapport.pdf');
+  await writeFile(source, 'fake pdf content');
+  const session = {
+    workspace: 'juno',
+    mcp: {},
+  };
+
+  try {
+    const { record, converted } = await storeAndMaybeConvertDocument(session, source);
+    assert.equal(converted, false);
+    assert.equal(record.workspace, 'juno');
+    assert.equal(record.status, 'stored');
+    assert.equal(record.agentPath.startsWith('/documents/input/juno/'), true);
+    assert.equal(await readFile(record.storedPath, 'utf8'), 'fake pdf content');
+
+    const uploads = await listDocumentUploads(session);
+    assert.equal(uploads.length, 1);
+    assert.equal(uploads[0].id, record.id);
+    assert.equal(uploads[0].error, 'documents MCP is not connected');
+  } finally {
+    if (originalAgentsDataDir === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = originalAgentsDataDir;
+  }
+});
+
+test('document intake accepts quoted absolute paths with spaces', async () => {
+  const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-'));
+  process.env.AGENTS_DATA_DIR = path.join(root, '.agents-data');
+  const source = path.join(root, 'Screenshot 2026-06-21 at 10.03.36.png');
+  await writeFile(source, 'fake png content');
+  const session = {
+    workspace: 'juno',
+    mcp: {},
+  };
+
+  try {
+    const { record } = await storeAndMaybeConvertDocument(session, `'${source}'`);
+    assert.equal(record.filename, 'Screenshot_2026-06-21_at_10.03.36.png');
+    assert.equal(await readFile(record.storedPath, 'utf8'), 'fake png content');
+  } finally {
+    if (originalAgentsDataDir === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = originalAgentsDataDir;
+  }
+});
+
+test('document intake accepts double-quoted absolute paths with spaces', async () => {
+  const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-'));
+  process.env.AGENTS_DATA_DIR = path.join(root, '.agents-data');
+  const source = path.join(root, 'scan avec espace.pdf');
+  await writeFile(source, 'fake pdf content');
+  const session = {
+    workspace: 'juno',
+    mcp: {},
+  };
+
+  try {
+    const { record } = await storeAndMaybeConvertDocument(session, `"${source}"`);
+    assert.equal(record.filename, 'scan_avec_espace.pdf');
+    assert.equal(await readFile(record.storedPath, 'utf8'), 'fake pdf content');
+  } finally {
+    if (originalAgentsDataDir === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = originalAgentsDataDir;
+  }
+});
+
+test('document intake replaces an existing upload with the same original filename', async () => {
+  const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-'));
+  const agentsDataDir = path.join(root, '.agents-data');
+  process.env.AGENTS_DATA_DIR = agentsDataDir;
+  const source = path.join(root, 'rapport.pdf');
+  const session = {
+    workspace: 'juno',
+    mcp: {},
+  };
+
+  try {
+    await writeFile(source, 'first pdf content');
+    const first = (await storeAndMaybeConvertDocument(session, source)).record;
+    const outputPath = path.join(root, 'workspace', 'raw', 'untracked', `${first.id}-rapport.md`);
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, 'old markdown');
+
+    const manifest = path.join(agentsDataDir, 'documents', 'uploads', 'juno.jsonl');
+    const firstRecord = JSON.parse(await readFile(manifest, 'utf8'));
+    await writeFile(manifest, `${JSON.stringify({ ...firstRecord, outputPath })}\n`, 'utf8');
+
+    await writeFile(source, 'second pdf content');
+    const second = (await storeAndMaybeConvertDocument(session, source)).record;
+
+    assert.notEqual(second.id, first.id);
+    assert.equal(existsSync(first.storedPath), false);
+    assert.equal(existsSync(outputPath), false);
+    assert.equal(await readFile(second.storedPath, 'utf8'), 'second pdf content');
+
+    const uploads = await listDocumentUploads(session);
+    assert.equal(uploads.length, 1);
+    assert.equal(uploads[0].id, second.id);
+    assert.equal(uploads[0].filename, 'rapport.pdf');
+  } finally {
+    if (originalAgentsDataDir === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = originalAgentsDataDir;
+  }
+});

package/src/core/env.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export function userManagerDir() {
+  return process.cwd();
+}
+
+export function managerEnvFile() {
+  return process.env.WIKI_MANAGER_ENV_FILE
+    ? resolve(process.env.WIKI_MANAGER_ENV_FILE)
+    : join(userManagerDir(), '.env');
+}
+
+export function managerMcpEndpointsFile() {
+  return join(userManagerDir(), 'mcp.endpoints.json');
+}
+
+function parseEnvValue(value) {
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value
+      .slice(1, -1)
+      .replace(/\\(["\\nrt])/g, (_match, char) => {
+        if (char === 'n') return '\n';
+        if (char === 'r') return '\r';
+        if (char === 't') return '\t';
+        return char;
+      });
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function loadManagerEnv() {
+  const filePath = managerEnvFile();
+  if (!existsSync(filePath)) return;
+  const values = readEnvFile(filePath);
+  for (const [key, value] of Object.entries(values)) {
+    if (!(key in process.env)) process.env[key] = value;
+  }
+}
+
+export function readEnvFile(filePath) {
+  const values = {};
+  const raw = readFileSync(filePath, 'utf8');
+  for (const sourceLine of raw.split(/\r?\n/)) {
+    const line = sourceLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex === -1) continue;
+    const key = line.slice(0, equalsIndex).trim();
+    const value = line.slice(equalsIndex + 1).trim();
+    values[key] = parseEnvValue(value);
+  }
+  return values;
+}

package/src/core/jobQueue.js

@@ -0,0 +1,197 @@
+import { extractActivity, parseJsonText, sessionActivities } from './activity.js';
+import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
+import { callMcpTool, formatMcpToolResult } from './mcp.js';
+
+const TERMINAL = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error']);
+
+function now() {
+  return new Date().toISOString();
+}
+
+function shortId() {
+  return `q-${Math.random().toString(16).slice(2, 6)}`;
+}
+
+function terminalStatus(status) {
+  return TERMINAL.has(String(status ?? '').toLowerCase());
+}
+
+export function ensureJobQueue(session) {
+  session.jobQueue ??= [];
+  return session.jobQueue;
+}
+
+export function productionLockBusy(session) {
+  return sessionActivities(session).some((activity) =>
+    activity.source === 'production' && !activity.terminal && activity.poll,
+  );
+}
+
+export function enqueueProductionJob(session, args = {}, reason = 'waiting') {
+  const workspace = session.workspace ?? null;
+  const item = {
+    id: shortId(),
+    workspace,
+    server: 'production',
+    tool: 'production_start_job',
+    args: { ...args },
+    lockKey: workspace ? `production:${workspace}` : 'production',
+    status: 'waiting',
+    reason,
+    createdAt: now(),
+  };
+  ensureJobQueue(session).push(item);
+  return item;
+}
+
+export function queueSummary(args = {}) {
+  const parts = [
+    args.type,
+    Array.isArray(args.steps) && args.steps.length ? `steps=${args.steps.join(',')}` : null,
+    Array.isArray(args.templates) && args.templates.length ? `templates=${args.templates.length}` : null,
+    Array.isArray(args.deliverables) && args.deliverables.length ? `deliverables=${args.deliverables.length}` : null,
+    args.configPath ? `config=${args.configPath}` : null,
+  ].filter(Boolean);
+  return parts.join(' ') || 'production job';
+}
+
+export function queueCounts(session) {
+  let active = 0;
+  let current = 0;
+  let frozen = 0;
+  for (const item of ensureJobQueue(session)) {
+    if (['waiting', 'starting', 'running'].includes(item.status)) {
+      active += 1;
+      if (item.workspace === session.workspace) current += 1;
+      else frozen += 1;
+    }
+  }
+  return { active, current, frozen };
+}
+
+export function formatQueue(session) {
+  const queue = ensureJobQueue(session);
+  if (queue.length === 0) return 'Queue is empty.';
+  return queue.map((item) => {
+    const frozen = item.workspace !== session.workspace && ['waiting', 'starting', 'running'].includes(item.status)
+      ? ' frozen'
+      : '';
+    const job = item.jobId ? ` job=${item.jobId}` : '';
+    const error = item.error ? ` error=${item.error}` : '';
+    return `${item.id} ${item.status}${frozen} ${item.workspace ?? 'no-workspace'} ${queueSummary(item.args)}${job}${error}`;
+  }).join('\n');
+}
+
+export function clearFinishedQueueItems(session) {
+  const queue = ensureJobQueue(session);
+  const before = queue.length;
+  session.jobQueue = queue.filter((item) =>
+    item.workspace !== session.workspace || !terminalStatus(item.status),
+  );
+  return before - session.jobQueue.length;
+}
+
+function findQueueItem(session, id) {
+  return ensureJobQueue(session).find((item) => item.id === id) ?? null;
+}
+
+export async function cancelQueueItem(session, id) {
+  const item = findQueueItem(session, id);
+  if (!item) return { ok: false, message: `Unknown queue item: ${id}` };
+  if (item.status === 'waiting' || item.status === 'starting') {
+    const label = item.status === 'starting' ? 'starting' : 'queued';
+    item.status = 'cancelled';
+    item.finishedAt = now();
+    return { ok: true, message: `Cancelled ${label} job ${id}.` };
+  }
+  if (item.status === 'running') {
+    if (item.server === 'production' && item.jobId) {
+      await callMcpTool(session.mcp, 'production', 'production_cancel_job', { jobId: item.jobId });
+      item.status = 'cancelled';
+      item.finishedAt = now();
+      return { ok: true, message: `Cancellation requested for ${id} (${item.jobId}).` };
+    }
+    return { ok: false, message: `No cancel tool available for ${id}.` };
+  }
+  return { ok: false, message: `Queue item ${id} is already ${item.status}.` };
+}
+
+function activeCurrentWorkspaceProductionJob(session) {
+  return productionLockBusy(session)
+    || ensureJobQueue(session).some((item) =>
+      item.workspace === session.workspace && ['starting', 'running'].includes(item.status),
+    );
+}
+
+function nextWaitingProductionItem(session) {
+  return ensureJobQueue(session).find((item) =>
+    item.workspace === session.workspace
+    && item.server === 'production'
+    && item.tool === 'production_start_job'
+    && item.status === 'waiting',
+  ) ?? null;
+}
+
+export async function startNextQueuedJob(session, hooks = {}) {
+  if (!session.workspace) return null;
+  if (activeCurrentWorkspaceProductionJob(session)) return null;
+  const item = nextWaitingProductionItem(session);
+  if (!item) return null;
+
+  item.status = 'starting';
+  item.startedAt = now();
+  hooks.refresh?.();
+  hooks.addLog?.(`queue: starting ${item.id} ${queueSummary(item.args)}`);
+
+  try {
+    const args = session.workspace && !item.args.callerLabel
+      ? { ...item.args, callerLabel: `${session.workspace}/wiki-manager` }
+      : item.args;
+    item.args = args;
+    const result = await callMcpTool(session.mcp, 'production', 'production_start_job', args);
+    const resultText = formatMcpToolResult(result);
+    const payload = parseJsonText(resultText);
+    if (payload?.ok === false && payload?.error === 'workspace_busy') {
+      item.status = 'waiting';
+      item.reason = 'workspace_busy';
+      hooks.addLog?.(`queue: ${item.id} still waiting, production lock busy`);
+      hooks.refresh?.();
+      return item;
+    }
+    const activity = extractActivity(payload, { server: 'production', tool: 'production_start_job' });
+    if (activity) {
+      item.status = activity.terminal ? activity.status : 'running';
+      item.jobId = activity.id;
+      item.activityKey = activity.key;
+      item.finishedAt = activity.terminal ? now() : undefined;
+      dispatchAgentEvent(session, createAgentEvent('activity_upserted', {
+        origin: 'queue',
+        payload: { activity },
+      }));
+    } else {
+      item.status = 'done';
+      item.finishedAt = now();
+    }
+    hooks.addLog?.(`queue: ${item.id} ${item.status}${item.jobId ? ` job=${item.jobId}` : ''}`);
+    hooks.refresh?.();
+    return item;
+  } catch (err) {
+    item.status = 'failed';
+    item.error = err instanceof Error ? err.message : String(err);
+    item.finishedAt = now();
+    hooks.addLog?.(`queue: ${item.id} failed · ${item.error}`);
+    hooks.refresh?.();
+    return item;
+  }
+}
+
+export function syncQueueWithActivity(session, activity) {
+  if (!activity?.id || activity.source !== 'production') return null;
+  const item = ensureJobQueue(session).find((entry) => entry.jobId === activity.id);
+  if (!item) return null;
+  item.status = activity.terminal ? activity.status : 'running';
+  item.activityKey = activity.key;
+  item.finishedAt = activity.terminal ? now() : item.finishedAt;
+  item.error = activity.error ?? item.error;
+  return item;
+}