feat: add task binding lifecycle and continuity helpers (#33)

Author: sven1103-agent

src/core/task-binding.js

@@ -0,0 +1,27 @@
+export function decideContinuity({ hasActiveTask = false, continuationSignal = false, distinctObjectiveSignal = false, alternativeRequested = false, ambiguous = false } = {}) {
+  if (!hasActiveTask) {
+    return { decision: "create-new", reason: "no-active-task" };
+  }
+
+  if (distinctObjectiveSignal || alternativeRequested) {
+    return { decision: "create-new", reason: alternativeRequested ? "alternative-requested" : "distinct-objective" };
+  }
+
+  if (ambiguous) {
+    return { decision: "ask-user", reason: "ambiguous-continuity" };
+  }
+
+  if (continuationSignal) {
+    return { decision: "reuse-active", reason: "clear-continuation" };
+  }
+
+  return { decision: "ask-user", reason: "insufficient-signal" };
+}
+
+export function inferTaskLifecycleTransition({ currentStatus = "inactive", explicitSignal = "none" } = {}) {
+  if (explicitSignal === "activate") return "active";
+  if (explicitSignal === "deactivate") return "inactive";
+  if (explicitSignal === "complete") return "completed";
+  if (explicitSignal === "block") return "blocked";
+  return currentStatus;
+}

src/core/worktree-service.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { parse } from "jsonc-parser";
+import { inferTaskLifecycleTransition } from "./task-binding.js";
 
 export const DEFAULTS = {
   branchPrefix: "wt/",
@@ -364,7 +365,13 @@ export function createWorktreeWorkflowService({ directory, git, stateStore }) {
     if (!sessionID || !stateStore) return;
     const state = await stateStore.loadSessionState(repoRoot, sessionID);
     const next = stateStore.setActiveTask(
-      stateStore.upsertTask(state, { title: prepared.title, branch: prepared.branch, worktree_path: prepared.worktree_path, status: "active" }),
+      stateStore.upsertTask(state, {
+        task_id: prepared.branch,
+        title: prepared.title,
+        branch: prepared.branch,
+        worktree_path: prepared.worktree_path,
+        status: inferTaskLifecycleTransition({ explicitSignal: "activate" }),
+      }),
       prepared.branch,
     );
     await stateStore.saveSessionState(repoRoot, sessionID, next);
@@ -373,7 +380,12 @@ export function createWorktreeWorkflowService({ directory, git, stateStore }) {
     if (!sessionID || !stateStore || removed.length === 0) return;
     let state = await stateStore.loadSessionState(repoRoot, sessionID);
     for (const item of removed) {
-      state = stateStore.upsertTask(state, { branch: item.branch, worktree_path: item.path, status: "cleaned" });
+      state = stateStore.upsertTask(state, {
+        task_id: item.branch,
+        branch: item.branch,
+        worktree_path: item.path,
+        status: inferTaskLifecycleTransition({ explicitSignal: "complete" }),
+      });
       if (stateStore.getActiveTask(state) === item.branch) {
         state = stateStore.setActiveTask(state, null);
       }

src/index.js

@@ -1,6 +1,7 @@
 import { tool } from "@opencode-ai/plugin";
 
 import { createWorktreeWorkflowService, __internalService, isMissingGitRepositoryError, isMissingRemoteError } from "./core/worktree-service.js";
+import { decideContinuity, inferTaskLifecycleTransition } from "./core/task-binding.js";
 import { createRuntimeStateStore } from "./runtime/state-store.js";
 
 function publishStructuredResult(context, result) {
@@ -27,6 +28,8 @@ export const __internal = {
   ...__internalService,
   isMissingGitRepositoryError,
   isMissingRemoteError,
+  decideContinuity,
+  inferTaskLifecycleTransition,
 };
 
 export const WorktreeWorkflowPlugin = async ({ $, directory }) => {

src/runtime/state-store.js

@@ -5,6 +5,88 @@ import path from "node:path";
 
 const STORE_VERSION = 1;
 
+const LIFECYCLE_VALUES = new Set(["active", "inactive", "completed", "blocked"]);
+
+function normalizeLifecycleStatus(value) {
+  if (value === "cleaned") return "completed";
+  return LIFECYCLE_VALUES.has(value) ? value : "inactive";
+}
+
+function createDefaultState(repoRoot, sessionID) {
+  return {
+    schema_version: STORE_VERSION,
+    repo_root: path.resolve(repoRoot),
+    session_id: sessionID,
+    active_task_id: null,
+    tasks: [],
+  };
+}
+
+function findTaskIndex(tasks, taskPatch) {
+  if (taskPatch?.task_id) {
+    const byID = tasks.findIndex((task) => task?.task_id === taskPatch.task_id);
+    if (byID !== -1) return byID;
+  }
+
+  return tasks.findIndex((task) => {
+    if (taskPatch?.branch && task?.branch === taskPatch.branch) return true;
+    if (taskPatch?.worktree_path && task?.worktree_path === taskPatch.worktree_path) return true;
+    return false;
+  });
+}
+
+function normalizeLoadedState(parsed, repoRoot, sessionID) {
+  if (!parsed || typeof parsed !== "object") return createDefaultState(repoRoot, sessionID);
+
+  const state = createDefaultState(repoRoot, sessionID);
+  const incomingTasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+  const legacyActiveTask = typeof parsed.active_task === "string" && parsed.active_task ? parsed.active_task : null;
+  const declaredActiveTask = typeof parsed.active_task_id === "string" && parsed.active_task_id ? parsed.active_task_id : null;
+
+  state.tasks = incomingTasks.map((task, index) => {
+    const normalized = {
+      ...(task && typeof task === "object" ? task : {}),
+      task_id: task?.task_id || task?.branch || task?.worktree_path || `task-${index + 1}`,
+      status: normalizeLifecycleStatus(task?.status),
+    };
+    return normalized;
+  });
+
+  let activeTaskID = declaredActiveTask;
+  if (!activeTaskID && legacyActiveTask) {
+    const legacyMatch = state.tasks.find((task) => task.task_id === legacyActiveTask || task.branch === legacyActiveTask);
+    activeTaskID = legacyMatch?.task_id ?? null;
+  }
+  if (!activeTaskID) {
+    const activeFromStatus = state.tasks.find((task) => task.status === "active");
+    activeTaskID = activeFromStatus?.task_id ?? null;
+  }
+  if (activeTaskID) {
+    const activeTask = state.tasks.find((task) => task.task_id === activeTaskID);
+    if (!activeTask || activeTask.status === "completed" || activeTask.status === "blocked") {
+      activeTaskID = null;
+    }
+  }
+
+  state.active_task_id = activeTaskID;
+  if (activeTaskID) {
+    state.tasks = state.tasks.map((task) => {
+      if (task.status === "completed" || task.status === "blocked") return task;
+      return {
+        ...task,
+        status: task.task_id === activeTaskID ? "active" : "inactive",
+      };
+    });
+  } else {
+    state.tasks = state.tasks.map((task) => {
+      if (task.status === "active") return { ...task, status: "inactive" };
+      return task;
+    });
+  }
+
+  return state;
+}
+
 function defaultStateDir(env = process.env, platform = process.platform) {
   if (env.OPENCODE_WORKTREE_STATE_DIR) {
     return path.resolve(env.OPENCODE_WORKTREE_STATE_DIR);
@@ -44,13 +126,10 @@ export function createRuntimeStateStore({ stateDir = defaultStateDir(), now = ()
     try {
       const raw = await fs.readFile(filePath, "utf8");
       const parsed = JSON.parse(raw);
-      if (!parsed || typeof parsed !== "object") {
-        return { schema_version: STORE_VERSION, repo_root: path.resolve(repoRoot), session_id: sessionID, active_task: null, tasks: [] };
-      }
-      return parsed;
+      return normalizeLoadedState(parsed, repoRoot, sessionID);
     } catch (error) {
       if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-        return { schema_version: STORE_VERSION, repo_root: path.resolve(repoRoot), session_id: sessionID, active_task: null, tasks: [] };
+        return createDefaultState(repoRoot, sessionID);
       }
       throw error;
     }
@@ -63,24 +142,40 @@ export function createRuntimeStateStore({ stateDir = defaultStateDir(), now = ()
   }
 
   function getActiveTask(state) {
-    return state?.active_task ?? null;
+    return state?.active_task_id ?? null;
   }
 
-  function setActiveTask(state, activeTask) {
+  function setActiveTask(state, activeTaskID) {
+    const tasks = Array.isArray(state?.tasks) ? state.tasks : [];
+    const nextTasks = tasks.map((task) => {
+      if (!task || typeof task !== "object") return task;
+      if (task.status === "completed" || task.status === "blocked") return task;
+      if (!activeTaskID) {
+        return task.status === "active" ? { ...task, status: "inactive" } : task;
+      }
+      return {
+        ...task,
+        status: task.task_id === activeTaskID ? "active" : "inactive",
+      };
+    });
+
     return {
       ...state,
-      active_task: activeTask,
+      active_task_id: activeTaskID,
+      tasks: nextTasks,
     };
   }
 
   function upsertTask(state, taskPatch) {
     const timestamp = now();
     const tasks = Array.isArray(state?.tasks) ? [...state.tasks] : [];
-    const index = tasks.findIndex((task) => task?.branch === taskPatch?.branch || task?.worktree_path === taskPatch?.worktree_path);
+    const index = findTaskIndex(tasks, taskPatch);
 
     if (index === -1) {
       tasks.push({
         ...taskPatch,
+        task_id: taskPatch?.task_id || taskPatch?.branch || taskPatch?.worktree_path || `task-${tasks.length + 1}`,
+        status: normalizeLifecycleStatus(taskPatch?.status),
         created_at: timestamp,
         last_used_at: timestamp,
       });
@@ -89,6 +184,8 @@ export function createRuntimeStateStore({ stateDir = defaultStateDir(), now = ()
       tasks[index] = {
         ...existing,
         ...taskPatch,
+        task_id: existing.task_id || taskPatch?.task_id || taskPatch?.branch || taskPatch?.worktree_path || `task-${index + 1}`,
+        status: normalizeLifecycleStatus(taskPatch?.status ?? existing.status),
         created_at: existing.created_at || timestamp,
         last_used_at: timestamp,
       };

test/base-branch.test.js

@@ -143,7 +143,7 @@ test("worktree_cleanup apply updates runtime state for removed task", async () =
     const stateFilePath = path.join(fixture.stateDir, "sessions", stateFiles[0]);
     const state = JSON.parse(await fs.readFile(stateFilePath, "utf8"));
     const task = state.tasks.find((item) => item.branch === prepared.result.branch);
-    assert.equal(task.status, "cleaned");
+    assert.equal(task.status, "completed");
   } finally {
     process.env.OPENCODE_WORKTREE_STATE_DIR = prev;
     await fixture.cleanup();

test/runtime-state-store.test.js

@@ -31,8 +31,41 @@ test("upsertTask preserves created_at and refreshes last_used_at", () => {
   let tick = 0;
   const store = createRuntimeStateStore({ stateDir: "/tmp/unused", now: () => `2026-03-27T00:00:0${++tick}Z` });
   const first = store.upsertTask({ tasks: [] }, { branch: "wt/a", worktree_path: "/tmp/a", status: "active" });
-  const second = store.upsertTask(first, { branch: "wt/a", status: "cleaned" });
+  const second = store.upsertTask(first, { branch: "wt/a", status: "completed" });
   assert.equal(second.tasks[0].created_at, "2026-03-27T00:00:01Z");
   assert.equal(second.tasks[0].last_used_at, "2026-03-27T00:00:02Z");
-  assert.equal(second.tasks[0].status, "cleaned");
+  assert.equal(second.tasks[0].status, "completed");
+});
+
+test("setActiveTask enforces single-active invariant", () => {
+  const store = createRuntimeStateStore({ stateDir: "/tmp/unused" });
+  const withA = store.upsertTask({ tasks: [] }, { task_id: "wt/a", branch: "wt/a", status: "active" });
+  const withB = store.upsertTask(withA, { task_id: "wt/b", branch: "wt/b", status: "inactive" });
+  const activatedB = store.setActiveTask(withB, "wt/b");
+
+  assert.equal(store.getActiveTask(activatedB), "wt/b");
+  assert.equal(activatedB.tasks.find((task) => task.task_id === "wt/a")?.status, "inactive");
+  assert.equal(activatedB.tasks.find((task) => task.task_id === "wt/b")?.status, "active");
+});
+
+test("loadSessionState migrates legacy active_task and cleaned status", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "wt-state-store-legacy-"));
+  try {
+    const store = createRuntimeStateStore({ stateDir: root });
+    const legacy = {
+      schema_version: 1,
+      repo_root: "/repo/path",
+      session_id: "session-legacy",
+      active_task: "wt/task",
+      tasks: [{ branch: "wt/task", worktree_path: "/tmp/wt/task", status: "cleaned" }],
+    };
+    await store.saveSessionState("/repo/path", "session-legacy", legacy);
+
+    const loaded = await store.loadSessionState("/repo/path", "session-legacy");
+    assert.equal(loaded.active_task_id, null);
+    assert.equal(loaded.tasks[0].task_id, "wt/task");
+    assert.equal(loaded.tasks[0].status, "completed");
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
 });

test/task-binding.test.js

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { __internal } from "../src/index.js";
+
+test("decideContinuity reuses active task for clear continuation", () => {
+  const decision = __internal.decideContinuity({ hasActiveTask: true, continuationSignal: true });
+  assert.deepEqual(decision, { decision: "reuse-active", reason: "clear-continuation" });
+});
+
+test("decideContinuity asks user when ambiguous", () => {
+  const decision = __internal.decideContinuity({ hasActiveTask: true, ambiguous: true });
+  assert.deepEqual(decision, { decision: "ask-user", reason: "ambiguous-continuity" });
+});
+
+test("decideContinuity creates new for distinct objective", () => {
+  const decision = __internal.decideContinuity({ hasActiveTask: true, distinctObjectiveSignal: true });
+  assert.deepEqual(decision, { decision: "create-new", reason: "distinct-objective" });
+});
+
+test("inferTaskLifecycleTransition only changes on explicit signal", () => {
+  assert.equal(__internal.inferTaskLifecycleTransition({ currentStatus: "active", explicitSignal: "none" }), "active");
+  assert.equal(__internal.inferTaskLifecycleTransition({ currentStatus: "active", explicitSignal: "complete" }), "completed");
+});