trackops 2.0.6 → 2.1.0

package/lib/server.js

@@ -402,26 +402,31 @@ function buildOperaState(projectRoot, controlState) {
   };
 }
 
-function getStatePayload(projectRef) {
-  const project = resolveProjectEntry(projectRef);
-  const api = loadControlApi(project.root);
-  const controlState = api.loadControl();
-  const runtime = api.refreshRepoRuntime({ quiet: true });
-  const envState = env.auditEnvironment(project.root, controlState);
-  const operaState = buildOperaState(project.root, controlState);
-
-  return {
-    project,
-    control: controlState,
-    derived: api.derive(controlState),
-    runtime,
-    env: envState,
-    opera: operaState,
-    docsDirty: api.getDocDrift(controlState),
-    i18n: buildI18nPayload(controlState),
-    generatedAt: new Date().toISOString(),
-  };
-}
+function getStatePayload(projectRef) {
+  const project = resolveProjectEntry(projectRef);
+  const api = loadControlApi(project.root);
+  const controlState = api.loadControl();
+  if (controlState.__trackopsMigrated) {
+    api.saveControl(controlState);
+  }
+  const runtime = api.refreshRepoRuntime({ quiet: true });
+  const envState = env.auditEnvironment(project.root, controlState);
+  const operaState = buildOperaState(project.root, controlState);
+  const quality = require("./quality");
+
+  return {
+    project,
+    control: controlState,
+    derived: api.derive(controlState),
+    runtime,
+    env: envState,
+    opera: operaState,
+    quality: quality.buildQualitySnapshot(project.root, controlState),
+    docsDirty: api.getDocDrift(controlState),
+    i18n: buildI18nPayload(controlState),
+    generatedAt: new Date().toISOString(),
+  };
+}
 
 function persist(projectRoot) {
   const api = loadControlApi(projectRoot);
@@ -458,72 +463,152 @@ function updateProjectLocale(projectRoot, locale) {
 
 /* ── task operations ── */
 
-function makeTaskId(controlState, seed) {
-  const base = slugify(seed) || `task-${Date.now()}`;
-  const existing = new Set(controlState.tasks.map((t) => t.id));
-  if (!existing.has(base)) return base;
-  let idx = 2;
-  while (existing.has(`${base}-${idx}`)) idx += 1;
-  return `${base}-${idx}`;
-}
-
-function createTask(projectRoot, payload) {
-  const api = loadControlApi(projectRoot);
-  const controlState = api.loadControl();
-  const title = String(payload.title || "").trim();
-  if (!title) throw new Error(t("server.titleRequired"));
-
-  const task = {
-    id: makeTaskId(controlState, payload.id || title),
-    title,
-    phase: payload.phase || config.getPhases(controlState)[0]?.id || "E",
-    stream: String(payload.stream || "Operations").trim(),
-    priority: payload.priority || "P1",
+function makeTaskId(controlState, seed) {
+  const base = slugify(seed) || `task-${Date.now()}`;
+  const existing = new Set(controlState.tasks.map((t) => t.id));
+  if (!existing.has(base)) return base;
+  let idx = 2;
+  while (existing.has(`${base}-${idx}`)) idx += 1;
+  return `${base}-${idx}`;
+}
+
+function normalizeSequenceValue(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function taskHasChildren(controlState, taskId) {
+  return (controlState.tasks || []).some((task) => String(task.parentId || "").trim() === taskId);
+}
+
+function assertValidParent(controlState, taskId, parentId) {
+  if (!parentId) return;
+  if (taskId && parentId === taskId) {
+    throw new Error("A task cannot be its own parent.");
+  }
+  const parent = (controlState.tasks || []).find((task) => task.id === parentId);
+  if (!parent) {
+    throw new Error(`Parent task not found: ${parentId}`);
+  }
+  if (!taskId) return;
+  const childrenByParent = new Map();
+  (controlState.tasks || []).forEach((task) => {
+    const key = String(task.parentId || "").trim();
+    if (!key) return;
+    if (!childrenByParent.has(key)) childrenByParent.set(key, []);
+    childrenByParent.get(key).push(task.id);
+  });
+  const stack = [...(childrenByParent.get(taskId) || [])];
+  const visited = new Set();
+  while (stack.length) {
+    const current = stack.pop();
+    if (visited.has(current)) continue;
+    if (current === parentId) {
+      throw new Error(`Parent cycle detected: '${taskId}' cannot move under '${parentId}'.`);
+    }
+    visited.add(current);
+    stack.push(...(childrenByParent.get(current) || []));
+  }
+}
+
+function createTask(projectRoot, payload) {
+  const api = loadControlApi(projectRoot);
+  const controlState = api.loadControl();
+  const title = String(payload.title || "").trim();
+  if (!title) throw new Error(t("server.titleRequired"));
+  const parentId = String(payload.parentId || "").trim() || null;
+  assertValidParent(controlState, null, parentId);
+
+  const task = config.normalizeTaskShape({
+    id: makeTaskId(controlState, payload.id || title),
+    title,
+    phase: payload.phase || config.getPhases(controlState)[0]?.id || "E",
+    stream: String(payload.stream || "Operations").trim(),
+    priority: payload.priority || "P1",
     status: payload.status || "pending",
     required: payload.required !== false,
-    dependsOn: toList(payload.dependsOn),
-    summary: String(payload.summary || "").trim(),
-    acceptance: toList(payload.acceptance),
-    history: [{ at: new Date().toISOString(), action: "create", note: t("server.taskCreatedNote") }],
-  };
-
-  const blocker = String(payload.blocker || "").trim();
-  if (blocker) task.blocker = blocker;
-  controlState.tasks.push(task);
-  api.saveControl(controlState);
+    dependsOn: toList(payload.dependsOn),
+    summary: String(payload.summary || "").trim(),
+    acceptance: toList(payload.acceptance),
+    parentId,
+    sequence: normalizeSequenceValue(payload.sequence),
+    origin: { kind: "manual" },
+    execution: {
+      owner: config.normalizeExecutionOwner(payload.executionOwner || payload.execution?.owner),
+      lastActor: String(payload.actor || "user").trim() || "user",
+      lastSource: String(payload.source || "dashboard").trim() || "dashboard",
+      currentSessionId: null,
+      lastSessionId: null,
+      lastSessionStatus: null,
+      awaitingUserConfirmation: false,
+      verificationPending: false,
+      updatedAt: new Date().toISOString(),
+    },
+    history: [{ at: new Date().toISOString(), action: "create", note: t("server.taskCreatedNote") }],
+  });
+
+  const blocker = String(payload.blocker || "").trim();
+  if (blocker) task.blocker = blocker;
+  controlState.tasks.push(task);
+  api.saveControl(controlState);
   api.syncDocs(controlState);
   api.refreshRepoRuntime({ quiet: true });
   return task;
 }
 
-function patchTask(projectRoot, taskId, payload) {
-  const api = loadControlApi(projectRoot);
-  const controlState = api.loadControl();
-  const task = controlState.tasks.find((t) => t.id === taskId);
-  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
-
-  if (typeof payload.title === "string") task.title = payload.title.trim() || task.title;
-  if (typeof payload.phase === "string") task.phase = payload.phase;
-  if (typeof payload.stream === "string") task.stream = payload.stream.trim() || task.stream;
-  if (typeof payload.priority === "string") task.priority = payload.priority;
-  if (typeof payload.status === "string") task.status = payload.status;
-  if (typeof payload.required === "boolean") task.required = payload.required;
-  if (payload.summary !== undefined) task.summary = String(payload.summary || "").trim();
-  if (payload.dependsOn !== undefined) task.dependsOn = toList(payload.dependsOn);
-  if (payload.acceptance !== undefined) task.acceptance = toList(payload.acceptance);
-
-  const blocker = String(payload.blocker || "").trim();
-  if (blocker) task.blocker = blocker;
-  else delete task.blocker;
-
-  task.history = task.history || [];
-  task.history.push({ at: new Date().toISOString(), action: "edit", note: String(payload.note || t("server.taskEditedNote")).trim() });
-
-  api.saveControl(controlState);
-  api.syncDocs(controlState);
-  api.refreshRepoRuntime({ quiet: true });
-  return task;
-}
+function patchTask(projectRoot, taskId, payload) {
+  const api = loadControlApi(projectRoot);
+  const controlState = api.loadControl();
+  const task = controlState.tasks.find((t) => t.id === taskId);
+  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
+  const actor = String(payload.actor || "user").trim() || "user";
+  const source = String(payload.source || "dashboard").trim() || "dashboard";
+
+  if (typeof payload.title === "string") task.title = payload.title.trim() || task.title;
+  if (typeof payload.phase === "string") task.phase = payload.phase;
+  if (typeof payload.stream === "string") task.stream = payload.stream.trim() || task.stream;
+  if (typeof payload.priority === "string") task.priority = payload.priority;
+  if (typeof payload.required === "boolean") task.required = payload.required;
+  if (payload.summary !== undefined) task.summary = String(payload.summary || "").trim();
+  if (payload.dependsOn !== undefined) task.dependsOn = toList(payload.dependsOn);
+  if (payload.acceptance !== undefined) task.acceptance = toList(payload.acceptance);
+  if (payload.parentId !== undefined) {
+    const parentId = String(payload.parentId || "").trim() || null;
+    assertValidParent(controlState, taskId, parentId);
+    task.parentId = parentId;
+  }
+  if (payload.sequence !== undefined) task.sequence = normalizeSequenceValue(payload.sequence);
+  if (payload.executionOwner !== undefined || payload.execution?.owner !== undefined) {
+    task.execution = config.normalizeTaskExecution({
+      ...(task.execution || {}),
+      owner: payload.executionOwner || payload.execution?.owner,
+      lastActor: actor,
+      lastSource: source,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  const blocker = String(payload.blocker || "").trim();
+  if (blocker) task.blocker = blocker;
+  else delete task.blocker;
+
+  if (typeof payload.status === "string") {
+    return api.setTaskStatus(controlState, taskId, payload.status, String(payload.note || t("server.taskEditedNote")).trim(), {
+      actor,
+      source,
+      owner: payload.executionOwner || payload.execution?.owner || task.execution?.owner,
+      historyAction: "edit",
+    });
+  }
+
+  task.history = task.history || [];
+  task.history.push({ at: new Date().toISOString(), action: "edit", note: String(payload.note || t("server.taskEditedNote")).trim() });
+  api.saveControl(controlState);
+  api.syncDocs(controlState);
+  api.refreshRepoRuntime({ quiet: true });
+  return task;
+}
 
 /* ── sessions (command execution) ── */
 
@@ -534,36 +619,90 @@ function cleanupSession(session) {
   if (session.maxRuntimeTimer) { clearTimeout(session.maxRuntimeTimer); session.maxRuntimeTimer = null; }
 }
 
-function terminateSession(session, reason) {
-  if (!session || session.status !== "running" || !session.process) return;
-  cleanupSession(session);
-  session.status = "terminated";
-  session.exitCode = 1;
-  session.output += `\n[ops] ${reason}\n`;
-  try { session.process.kill(); } catch (_e) { /* noop */ }
-  session.listeners.forEach((res) => {
-    emitSession(res, { type: "done", status: session.status, exitCode: session.exitCode, output: session.output, projectId: session.projectId });
-    res.end();
-  });
+function terminateSession(session, reason) {
+  if (!session || session.status !== "running" || !session.process) return;
+  cleanupSession(session);
+  session.status = "terminated";
+  session.exitCode = 1;
+  session.output += `\n[ops] ${reason}\n`;
+  try { session.process.kill(); } catch (_e) { /* noop */ }
+  updateTaskSessionContext(session, "terminated");
+  session.listeners.forEach((res) => {
+    emitSession(res, { type: "done", status: session.status, exitCode: session.exitCode, output: session.output, projectId: session.projectId });
+    res.end();
+  });
   session.listeners.clear();
 }
 
-function scheduleOrphanTermination(session) {
-  if (!session || session.status !== "running" || session.listeners.size > 0) return;
-  cleanupSession(session);
-  session.killTimer = setTimeout(() => terminateSession(session, "orphan timeout"), ORPHAN_TIMEOUT_MS);
-}
-
-function createSession(commandText, project) {
-  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  const session = {
-    id, projectId: project.id, projectName: project.name, projectRoot: project.root,
-    command: commandText, startedAt: new Date().toISOString(),
-    status: "running", exitCode: null, output: "", listeners: new Set(),
-  };
-
-  const shell = process.platform === "win32" ? "powershell.exe" : process.env.SHELL || "/bin/sh";
-  const shellArgs = process.platform === "win32"
+function scheduleOrphanTermination(session) {
+  if (!session || session.status !== "running" || session.listeners.size > 0) return;
+  cleanupSession(session);
+  session.killTimer = setTimeout(() => terminateSession(session, "orphan timeout"), ORPHAN_TIMEOUT_MS);
+}
+
+function updateTaskSessionContext(session, sessionStatus) {
+  if (!session?.taskId) return;
+  const api = loadControlApi(session.projectRoot);
+  const controlState = api.loadControl();
+  const task = (controlState.tasks || []).find((item) => item.id === session.taskId);
+  if (!task) return;
+
+  task.execution = config.normalizeTaskExecution({
+    ...(task.execution || {}),
+    lastActor: "agent",
+    lastSource: session.source || "execution_console",
+    lastSessionId: session.id,
+    lastSessionStatus: sessionStatus || null,
+    currentSessionId: sessionStatus === "running" ? session.id : null,
+    updatedAt: new Date().toISOString(),
+  });
+
+  api.saveControl(controlState);
+  api.syncDocs(controlState);
+  api.refreshRepoRuntime({ quiet: true });
+}
+
+function createSession(commandText, project, options = {}) {
+  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const session = {
+    id, projectId: project.id, projectName: project.name, projectRoot: project.root,
+    command: commandText, startedAt: new Date().toISOString(),
+    status: "running", exitCode: null, output: "", listeners: new Set(),
+    taskId: options.taskId ? String(options.taskId).trim() : null,
+    source: options.source ? String(options.source).trim() : "execution_console",
+  };
+
+  if (session.taskId) {
+    const api = loadControlApi(project.root);
+    const controlState = api.loadControl();
+    const task = (controlState.tasks || []).find((item) => item.id === session.taskId);
+    if (!task) throw new Error(t("server.timeTaskNotFound", { taskId: session.taskId }));
+    if (taskHasChildren(controlState, session.taskId)) {
+      throw new Error(t("server.timeParentTask"));
+    }
+    if (task.status === "pending" || task.status === "blocked") {
+      api.updateTask(controlState, "start", session.taskId, t("server.agentExecutionStarted"), {
+        actor: "agent",
+        source: session.source,
+        sessionId: id,
+      });
+    } else {
+      task.execution = config.normalizeTaskExecution({
+        ...(task.execution || {}),
+        lastActor: "agent",
+        lastSource: session.source,
+        currentSessionId: id,
+        lastSessionId: id,
+        updatedAt: new Date().toISOString(),
+      });
+      api.saveControl(controlState);
+      api.syncDocs(controlState);
+      api.refreshRepoRuntime({ quiet: true });
+    }
+  }
+
+  const shell = process.platform === "win32" ? "powershell.exe" : process.env.SHELL || "/bin/sh";
+  const shellArgs = process.platform === "win32"
     ? ["-NoLogo", "-NoProfile", "-Command", commandText]
     : ["-lc", commandText];
 
@@ -579,27 +718,29 @@ function createSession(commandText, project) {
     session.listeners.forEach((res) => emitSession(res, { type, chunk: text, status: session.status, projectId: session.projectId }));
   }
 
-  child.stdout.on("data", (c) => pushChunk("stdout", c));
-  child.stderr.on("data", (c) => pushChunk("stderr", c));
-  child.on("close", (code) => {
-    cleanupSession(session);
-    session.status = "completed";
-    session.exitCode = code;
-    session.listeners.forEach((res) => {
-      emitSession(res, { type: "done", status: session.status, exitCode: code, output: session.output, projectId: session.projectId });
-      res.end();
-    });
-    session.listeners.clear();
-  });
-  child.on("error", (err) => {
-    cleanupSession(session);
-    session.status = "failed";
-    session.exitCode = 1;
-    session.output += `${err.message}\n`;
-    session.listeners.forEach((res) => {
-      emitSession(res, { type: "done", status: session.status, exitCode: 1, output: session.output, projectId: session.projectId });
-      res.end();
-    });
+  child.stdout.on("data", (c) => pushChunk("stdout", c));
+  child.stderr.on("data", (c) => pushChunk("stderr", c));
+  child.on("close", (code) => {
+    cleanupSession(session);
+    session.status = "completed";
+    session.exitCode = code;
+    updateTaskSessionContext(session, code === 0 ? "completed" : "failed");
+    session.listeners.forEach((res) => {
+      emitSession(res, { type: "done", status: session.status, exitCode: code, output: session.output, projectId: session.projectId });
+      res.end();
+    });
+    session.listeners.clear();
+  });
+  child.on("error", (err) => {
+    cleanupSession(session);
+    session.status = "failed";
+    session.exitCode = 1;
+    session.output += `${err.message}\n`;
+    updateTaskSessionContext(session, "failed");
+    session.listeners.forEach((res) => {
+      emitSession(res, { type: "done", status: session.status, exitCode: 1, output: session.output, projectId: session.projectId });
+      res.end();
+    });
     session.listeners.clear();
   });
 
@@ -694,15 +835,158 @@ async function handleApi(req, res, url) {
       return;
     }
 
-    if (req.method === "GET" && url.pathname === "/api/state") {
-      sendJson(res, 200, getStatePayload(url.searchParams.get("project")));
-      return;
-    }
-
-    if (req.method === "POST" && url.pathname === "/api/projects/locale") {
-      const body = await parseBody(req);
-      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
-      const controlState = updateProjectLocale(project.root, body.locale);
+    if (req.method === "GET" && url.pathname === "/api/state") {
+      sendJson(res, 200, getStatePayload(url.searchParams.get("project")));
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/plans") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const plans = require("./plans");
+      sendJson(res, 200, { ok: true, sources: plans.listSources(project.root) });
+      return;
+    }
+
+    const planMatch = url.pathname.match(/^\/api\/plans\/([^/]+)$/);
+    if (req.method === "GET" && planMatch) {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const plans = require("./plans");
+      sendJson(res, 200, { ok: true, ...plans.loadSource(project.root, decodeURIComponent(planMatch[1])) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/plans/scan") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const plans = require("./plans");
+      sendJson(res, 200, { ok: true, candidates: plans.scan(project.root, { path: body.path || null }) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/plans/import") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const plans = require("./plans");
+      const result = plans.importPlan(project.root, {
+        file: body.file,
+        adapter: body.adapter || "auto",
+        sourceId: body.sourceId || null,
+      });
+      const api = loadControlApi(project.root);
+      api.syncDocs(result.control);
+      api.refreshRepoRuntime({ quiet: true });
+      sendJson(res, 201, { ok: true, ...result, state: getStatePayload(project.id) });
+      return;
+    }
+
+    const planApplyMatch = url.pathname.match(/^\/api\/plans\/([^/]+)\/apply$/);
+    if (req.method === "POST" && planApplyMatch) {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const plans = require("./plans");
+      const result = plans.applyPlan(project.root, decodeURIComponent(planApplyMatch[1]), {
+        importId: body.importId || "latest",
+        conflicts: body.conflicts || "abort",
+        removed: body.removed || "detach",
+      });
+      const api = loadControlApi(project.root);
+      api.syncDocs(result.control);
+      api.refreshRepoRuntime({ quiet: true });
+      sendJson(res, 200, { ok: true, ...result, state: getStatePayload(project.id) });
+      return;
+    }
+
+    const planUnlinkMatch = url.pathname.match(/^\/api\/plans\/([^/]+)\/unlink$/);
+    if (req.method === "POST" && planUnlinkMatch) {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const plans = require("./plans");
+      const result = plans.unlinkSource(project.root, decodeURIComponent(planUnlinkMatch[1]), {
+        keepTasks: body.keepTasks === true,
+      });
+      const api = loadControlApi(project.root);
+      api.syncDocs(result.control);
+      api.refreshRepoRuntime({ quiet: true });
+      sendJson(res, 200, { ok: true, ...result, state: getStatePayload(project.id) });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/quality") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const quality = require("./quality");
+      sendJson(res, 200, { ok: true, ...quality.buildQualitySnapshot(project.root) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/quality/verify") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const quality = require("./quality");
+      const run = quality.verify(project.root, {
+        scope: body.scope || "all",
+        note: body.note || "",
+      });
+      sendJson(res, 200, { ok: true, run, state: getStatePayload(project.id) });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/quality/phase-readiness") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const quality = require("./quality");
+      sendJson(res, 200, {
+        ok: true,
+        ...quality.buildPhaseReadiness(project.root, null, {
+          phase: url.searchParams.get("phase") || "current",
+        }),
+      });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/quality/release-readiness") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const quality = require("./quality");
+      sendJson(res, 200, { ok: true, ...quality.buildReleaseReadiness(project.root) });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/quality/promotion-readiness") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const quality = require("./quality");
+      sendJson(res, 200, {
+        ok: true,
+        ...quality.buildPromotionReadiness(project.root, null, {
+          target: url.searchParams.get("target") || "staging",
+        }),
+      });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/quality/waivers") {
+      const project = resolveProjectEntry(url.searchParams.get("project"));
+      const quality = require("./quality");
+      sendJson(res, 200, { ok: true, waivers: quality.listWaivers(project.root) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/quality/waivers") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const quality = require("./quality");
+      const waiver = quality.addWaiver(project.root, {
+        probeId: body.probeId,
+        scope: body.scope,
+        reason: body.reason,
+        approvedBy: body.approvedBy,
+        expiresAt: body.expiresAt,
+      });
+      sendJson(res, 201, { ok: true, waiver, state: getStatePayload(project.id) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/projects/locale") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const controlState = updateProjectLocale(project.root, body.locale);
       sendJson(res, 200, {
         ok: true,
         locale: config.getLocale(controlState),
@@ -728,18 +1012,21 @@ async function handleApi(req, res, url) {
       return;
     }
 
-    const actionMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/action$/);
-    if (req.method === "POST" && actionMatch) {
-      const body = await parseBody(req);
-      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
-      const action = String(body.action || "").trim();
-      if (!action) { sendJson(res, 400, { ok: false, error: "Action required." }); return; }
-      const api = loadControlApi(project.root);
-      const controlState = api.loadControl();
-      api.updateTask(controlState, action, decodeURIComponent(actionMatch[1]), body.note || "");
-      sendJson(res, 200, { ok: true, state: getStatePayload(project.id) });
-      return;
-    }
+    const actionMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/action$/);
+    if (req.method === "POST" && actionMatch) {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const action = String(body.action || "").trim();
+      if (!action) { sendJson(res, 400, { ok: false, error: "Action required." }); return; }
+      const api = loadControlApi(project.root);
+      const controlState = api.loadControl();
+      api.updateTask(controlState, action, decodeURIComponent(actionMatch[1]), body.note || "", {
+        actor: String(body.actor || "user").trim() || "user",
+        source: String(body.source || "dashboard").trim() || "dashboard",
+      });
+      sendJson(res, 200, { ok: true, state: getStatePayload(project.id) });
+      return;
+    }
 
     if (req.method === "POST" && url.pathname === "/api/sync") {
       const body = await parseBody(req);
@@ -942,15 +1229,18 @@ async function handleApi(req, res, url) {
       return;
     }
 
-    if (req.method === "POST" && url.pathname === "/api/commands") {
-      const body = await parseBody(req);
-      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
-      const commandText = String(body.command || "").trim();
-      if (!commandText) { sendJson(res, 400, { ok: false, error: t("server.commandRequired") }); return; }
-      const session = createSession(commandText, project);
-      sendJson(res, 201, { ok: true, session: { id: session.id, command: session.command, startedAt: session.startedAt, status: session.status, projectId: session.projectId, projectName: session.projectName } });
-      return;
-    }
+    if (req.method === "POST" && url.pathname === "/api/commands") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const commandText = String(body.command || "").trim();
+      if (!commandText) { sendJson(res, 400, { ok: false, error: t("server.commandRequired") }); return; }
+      const session = createSession(commandText, project, {
+        taskId: body.taskId || null,
+        source: body.source || "execution_console",
+      });
+      sendJson(res, 201, { ok: true, session: { id: session.id, command: session.command, startedAt: session.startedAt, status: session.status, projectId: session.projectId, projectName: session.projectName } });
+      return;
+    }
 
     const sessionInfoMatch = url.pathname.match(/^\/api\/commands\/([^/]+)$/);
     if (req.method === "GET" && sessionInfoMatch) {
@@ -988,41 +1278,63 @@ async function handleApi(req, res, url) {
       return;
     }
 
-    if (req.method === "POST" && url.pathname === "/api/time/start") {
-      const body = await parseBody(req);
-      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
-      const api = loadControlApi(project.root);
-      const controlState = api.loadControl();
-      const entryId = `te-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
-      const entry = {
-        id:        entryId,
-        taskId:    String(body.taskId || "").trim(),
-        taskTitle: String(body.taskTitle || "").trim(),
-        startedAt: new Date().toISOString(),
-        stoppedAt: null,
-        durationMs: 0,
-      };
-      if (!controlState.timeEntries) controlState.timeEntries = [];
-      controlState.timeEntries.push(entry);
-      api.saveControl(controlState);
-      sendJson(res, 201, { ok: true, entry });
-      return;
-    }
-
-    if (req.method === "POST" && url.pathname === "/api/time/stop") {
-      const body = await parseBody(req);
-      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
-      const api = loadControlApi(project.root);
-      const controlState = api.loadControl();
-      const entries = controlState.timeEntries || [];
-      const entry = entries.find(e => e.id === body.entryId);
-      if (!entry) { sendJson(res, 404, { ok: false, error: "Entry not found." }); return; }
-      entry.stoppedAt  = new Date().toISOString();
-      entry.durationMs = new Date(entry.stoppedAt) - new Date(entry.startedAt);
-      api.saveControl(controlState);
-      sendJson(res, 200, { ok: true, entry });
-      return;
-    }
+    if (req.method === "POST" && url.pathname === "/api/time/start") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const api = loadControlApi(project.root);
+      const controlState = api.loadControl();
+      const taskId = String(body.taskId || "").trim();
+      if (!taskId) { sendJson(res, 400, { ok: false, error: t("server.timeTaskRequired") }); return; }
+      const task = (controlState.tasks || []).find((item) => item.id === taskId);
+      if (!task) { sendJson(res, 404, { ok: false, error: t("server.timeTaskNotFound", { taskId }) }); return; }
+      if (taskHasChildren(controlState, taskId)) {
+        sendJson(res, 400, { ok: false, error: t("server.timeParentTask") });
+        return;
+      }
+      const entryId = `te-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+      const entry = {
+        id:        entryId,
+        taskId,
+        taskTitle: String(body.taskTitle || "").trim() || task.title,
+        startedAt: new Date().toISOString(),
+        stoppedAt: null,
+        durationMs: 0,
+      };
+      if (!controlState.timeEntries) controlState.timeEntries = [];
+      controlState.timeEntries.push(entry);
+      const shouldAutoStart = task.status === "pending" || task.status === "blocked";
+      if (shouldAutoStart) {
+        api.updateTask(controlState, "start", taskId, t("server.timeStartedNote"), {
+          actor: String(body.actor || "user").trim() || "user",
+          source: String(body.source || "time_tracker").trim() || "time_tracker",
+        });
+      } else {
+        task.execution = config.normalizeTaskExecution({
+          ...(task.execution || {}),
+          lastActor: String(body.actor || "user").trim() || "user",
+          lastSource: String(body.source || "time_tracker").trim() || "time_tracker",
+          updatedAt: new Date().toISOString(),
+        });
+        api.saveControl(controlState);
+      }
+      sendJson(res, 201, { ok: true, entry, autoTaskStarted: shouldAutoStart, state: getStatePayload(project.id) });
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/time/stop") {
+      const body = await parseBody(req);
+      const project = resolveProjectEntry(body.projectId || body.project || url.searchParams.get("project"));
+      const api = loadControlApi(project.root);
+      const controlState = api.loadControl();
+      const entries = controlState.timeEntries || [];
+      const entry = entries.find(e => e.id === body.entryId);
+      if (!entry) { sendJson(res, 404, { ok: false, error: t("server.timeEntryNotFound") }); return; }
+      entry.stoppedAt  = new Date().toISOString();
+      entry.durationMs = new Date(entry.stoppedAt) - new Date(entry.startedAt);
+      api.saveControl(controlState);
+      sendJson(res, 200, { ok: true, entry, state: getStatePayload(project.id) });
+      return;
+    }
 
     /* ── Skills Hub ── */