@saadnvd1/agent-os 0.3.597 → 0.3.600

package/lib/tasks/index.ts

@@ -48,7 +48,9 @@ import {
 } from "./state";
 import { expandHome, prFor, storedPR, taskSessions } from "./session";
 import { InProgressError, type OrchestratedBundle } from "./move-bundle";
-import { holdFor, mayHold, recordStarter } from "./held";
+import { holdFor, mayHold } from "./held";
+import { orchestratorOf, recordStart, type StartVia } from "./starter";
+import { claimable, claimPiece, releaseClaim } from "../plans/claim";
 import { nameFor } from "../session-titles";
 import { taskSetupOf, type TaskSetup } from "./setup";
 import { taskPlan } from "./plan-view";
@@ -136,8 +138,13 @@ export async function createTask(opts: {
   planReason?: string | null;
   // Stop after the plan and wait for approval (implies plan).
   planOnly?: boolean;
-  // The orchestrator session that started it (null: a person).
+  // The session that started it (null: a person), the session it came from,
+  // and how: every start says (tasks/starter.ts).
   startedBy?: string | null;
+  parentSessionId?: string | null;
+  startedVia: StartVia;
+  // The waiting plan piece it builds: claimed for this task.
+  pieceId?: number;
   // Started from this LumifyHub card, which the task then moves.
   cardId?: string;
   // Stacked: cut from another task's pushed branch, at this exact commit.
@@ -165,7 +172,7 @@ export async function createTask(opts: {
   // (held.ts): that machine's paired device and its description of the task.
   held?: { device: string; orchestrated: OrchestratedBundle };
   // The paired device that sent this keyed start: the only one that may hold it later.
-  startedByDevice?: string;
+  startedByDevice?: string | null;
 }): Promise<Session> {
   if (opts.id) {
     const existing = queries.getSession(db).get(opts.id) as Session | undefined;
@@ -222,6 +229,7 @@ async function startTask(
   if (!prompt) throw new Error("Describe the task");
   const project = getProject(opts.projectId);
   if (!project || project.is_uncategorized) throw new Error("Pick a project");
+  if (opts.pieceId) claimable(opts.pieceId);
   const hostId = opts.hostId ?? project.host_id;
   const view = opts.view ?? DEFAULT_START_VIEW;
   const agent = opts.agent ?? "claude";
@@ -251,6 +259,16 @@ async function startTask(
       view,
       startedBy: opts.startedBy,
     });
+    // The mirror's started_by stays orchestrator-only: a held-remote task is
+    // relayed, stopped and answered through it. A plain calling task is its
+    // parent and started_via only.
+    recordStart(session.id, {
+      startedBy: orchestratorOf(opts.startedBy),
+      parentSessionId: opts.parentSessionId ?? null,
+      startedVia: opts.startedVia,
+      startedByDevice: opts.held?.device ?? opts.startedByDevice,
+    });
+    if (opts.pieceId) claimPiece(opts.pieceId, session.id);
     opts.onCreated?.(session.id);
     return session;
   }
@@ -295,50 +313,71 @@ async function startTask(
   const model = routing.first.model;
   const tmuxName = `${provider.id}-${id}`;
 
-  queries
-    .createSession(db)
-    .run(
-      id,
-      naming.name,
-      tmuxName,
-      wt.worktreePath,
-      null,
-      model,
-      null,
-      "sessions",
-      agent,
-      1,
-      project.id,
-      "local"
+  // Claimed right before the row exists, with nothing awaited between, so the
+  // release sweep can't start the same piece.
+  if (opts.pieceId) {
+    try {
+      claimPiece(opts.pieceId, id);
+    } catch (error) {
+      await discardLeftoverStart(projectPath, feature).catch(() => {});
+      throw error;
+    }
+  }
+  try {
+    queries
+      .createSession(db)
+      .run(
+        id,
+        naming.name,
+        tmuxName,
+        wt.worktreePath,
+        null,
+        model,
+        null,
+        "sessions",
+        agent,
+        1,
+        project.id,
+        "local"
+      );
+    queries
+      .updateSessionWorktree(db)
+      .run(wt.worktreePath, wt.branchName, baseBranch, null, id);
+    // Everything the launch needs is on the row, so a restart can resume it.
+    db.prepare(
+      `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', setup_status = 'running', name_source = ?, view = ?,
+         model_provider = ?, model_overrides = ?, plan_phase = ?, plan_only = ?,
+         plan_decided = ?, plan_reason = ? WHERE id = ?`
+    ).run(
+      prompt,
+      buildTaskBrief({
+        branch: wt.branchName,
+        baseBranch,
+        stack: opts.base?.stack,
+      }),
+      naming.source,
+      view,
+      routing.first.provider.id === ANTHROPIC
+        ? null
+        : routing.first.provider.id,
+      routing.override ? JSON.stringify(routing.override) : null,
+      routing.plan ? "planning" : null,
+      routing.planOnly ? 1 : null,
+      routing.planOnly ? 1 : opts.plan === undefined ? null : opts.plan ? 1 : 0,
+      opts.planReason?.trim() || null,
+      id
     );
-  queries
-    .updateSessionWorktree(db)
-    .run(wt.worktreePath, wt.branchName, baseBranch, null, id);
-  // Everything the launch needs is on the row, so a restart can resume it.
-  db.prepare(
-    `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', setup_status = 'running', name_source = ?, view = ?,
-       model_provider = ?, model_overrides = ?, plan_phase = ?, plan_only = ?,
-       plan_decided = ?, plan_reason = ?, started_by = ? WHERE id = ?`
-  ).run(
-    prompt,
-    buildTaskBrief({
-      branch: wt.branchName,
-      baseBranch,
-      stack: opts.base?.stack,
-    }),
-    naming.source,
-    view,
-    routing.first.provider.id === ANTHROPIC ? null : routing.first.provider.id,
-    routing.override ? JSON.stringify(routing.override) : null,
-    routing.plan ? "planning" : null,
-    routing.planOnly ? 1 : null,
-    routing.planOnly ? 1 : opts.plan === undefined ? null : opts.plan ? 1 : 0,
-    opts.planReason?.trim() || null,
-    opts.startedBy ?? null,
-    id
-  );
-  const starter = opts.held?.device ?? opts.startedByDevice;
-  if (starter) recordStarter(id, starter);
+    recordStart(id, {
+      startedBy: opts.startedBy ?? null,
+      parentSessionId: opts.parentSessionId ?? null,
+      startedVia: opts.startedVia,
+      startedByDevice: opts.held?.device ?? opts.startedByDevice,
+    });
+  } catch (error) {
+    // The claim was made for a session that never existed.
+    if (opts.pieceId) releaseClaim(opts.pieceId, id);
+    throw error;
+  }
   if (opts.held) holdFor(id, opts.held.device, opts.held.orchestrated);
   opts.onCreated?.(id);
   void naming.refine?.(id);

package/lib/tasks/move-carry.ts

@@ -9,6 +9,7 @@
 
 import type Database from "better-sqlite3";
 import { db } from "../db";
+import { orchestratorOf } from "./starter";
 
 // table, column, and how the id sits in it: the whole value, `task:<id>`, or
 // the tail of a `<condition>:<id>` key.
@@ -59,9 +60,19 @@ export const CARRIED_COLUMNS = [
 ] as const;
 
 /** The orchestration columns that make a session "an orchestrator's task". */
+// started_by carries as the orchestrator only: a task a plain task started is
+// not held, and a mirror reading it as held would relay to the wrong session.
 export const orchestrationOf = (session: Record<string, unknown>) =>
   Object.fromEntries(
-    CARRIED_COLUMNS.map((c) => [c, session[c] ?? null] as const)
+    CARRIED_COLUMNS.map(
+      (c) =>
+        [
+          c,
+          c === "started_by"
+            ? orchestratorOf(session.started_by as string | null)
+            : (session[c] ?? null),
+        ] as const
+    )
   );
 
 export function carryTaskState(

package/lib/tasks/move-guard.ts

@@ -10,10 +10,11 @@ import { db, type Session } from "../db";
 import { escalations } from "../orchestrator/gates";
 import { taskSubject } from "../orchestrator/asks";
 import { usesGitCrypt } from "../worktree-add";
+import { orchestratorOf } from "./starter";
 
 /** Started by an orchestrator, or held for one by the machine it left. */
 export function isOrchestrated(session: Session): boolean {
-  if (session.started_by || session.held_by_device) return true;
+  if (orchestratorOf(session.started_by) || session.held_by_device) return true;
   return !!db
     .prepare(
       `SELECT 1 FROM orchestrator_starts WHERE kind != 'stack' AND target = ? LIMIT 1`

package/lib/tasks/move.ts

@@ -30,6 +30,7 @@ import { dropSessionDatabase } from "../project-config/database";
 import { releaseChat } from "../chat/runner";
 import { collectWhileMoving } from "../chat/hold";
 import { packChat, stopChatForMove } from "./move-chat";
+import { orchestratorOf as starterOrchestrator } from "./starter";
 import {
   isClaudeSessionId,
   latestSessionId,
@@ -122,11 +123,12 @@ function orchestratorOf(
 ): { id: string; name: string } | undefined {
   if (session.held_for && session.held_for_name)
     return { id: session.held_for, name: session.held_for_name };
-  if (!session.started_by) return undefined;
-  const o = db
-    .prepare(`SELECT name FROM sessions WHERE id = ?`)
-    .get(session.started_by) as { name: string } | undefined;
-  return o ? { id: session.started_by, name: o.name } : undefined;
+  const by = starterOrchestrator(session.started_by);
+  if (!by) return undefined;
+  const o = db.prepare(`SELECT name FROM sessions WHERE id = ?`).get(by) as
+    | { name: string }
+    | undefined;
+  return o ? { id: by, name: o.name } : undefined;
 }
 
 // What an orchestrator's task carries besides its work (the orchestrator's

package/lib/tasks/pause.ts

@@ -28,7 +28,7 @@ import { launchPending } from "./launch-gate";
 import { killTmux } from "./start";
 import { launchClaude } from "../agents/launch";
 import { resolveRole, sessionWorkspace, taskOverride } from "../models/resolve";
-import { sessionRole } from "../models/roles";
+import { sessionRole } from "../models/session-role";
 import { holdingEscalations } from "../orchestrator/gates";
 import { openBySubject, workSubject } from "../orchestrator/asks";
 import { queueEventOnce } from "../orchestrator/events";

package/lib/tasks/queue.ts

@@ -85,6 +85,8 @@ import {
   resumeHoldFor,
   setPauseNote,
 } from "./pause";
+import { orchestratorOf, type StartVia } from "./starter";
+import { claimPiece } from "../plans/claim";
 
 export type QueueStatus =
   | "queued"
@@ -107,6 +109,9 @@ export interface QueueRow {
   plan_reason: string | null;
   plan_only: number | null;
   started_by: string | null;
+  parent_session_id: string | null;
+  started_by_device: string | null;
+  started_via: string | null;
   view: "chat" | "terminal" | null;
   agent_type: string | null;
   base_branch: string | null;
@@ -306,6 +311,11 @@ export interface QueueRequest {
   planReason?: string | null;
   planOnly?: boolean;
   startedBy?: string | null;
+  parentSessionId?: string | null;
+  startedByDevice?: string | null;
+  startedVia: StartVia;
+  // The waiting plan piece it builds, claimed for its queue id.
+  pieceId?: number;
   view?: "chat" | "terminal";
   agent?: AgentType;
   baseBranch?: string;
@@ -412,36 +422,43 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
   if (!waits && !full && !loaded) return null;
   if (!req.prompt.trim()) throw new Error("Describe the task");
   const id = randomUUID();
-  db.prepare(
-    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, plan_only, started_by, view, agent_type, base_branch,
-       host_id, after_task, after_any, origin_workspace_id, priority, machine_needs, position)
-     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @plan_only, @started_by, @view, @agent_type, @base_branch,
-       @host_id, @after_task, @after_any, @origin, @priority, @machine_needs,
-       (SELECT COALESCE(MAX(position), 0) + 1 FROM task_queue))`
-  ).run({
-    id,
-    project_id: project.id,
-    prompt: req.prompt.trim(),
-    name: req.name?.trim() || null,
-    model: typeof req.model === "string" ? req.model || null : null,
-    model_overrides:
-      req.model && typeof req.model === "object"
-        ? JSON.stringify(req.model)
-        : null,
-    plan: req.plan === undefined ? null : req.plan ? 1 : 0,
-    plan_reason: req.planReason?.trim() || null,
-    plan_only: req.planOnly ? 1 : null,
-    started_by: req.startedBy ?? null,
-    view: req.view ?? null,
-    agent_type: req.agent ?? null,
-    base_branch: req.baseBranch || null,
-    host_id: req.hostId || null,
-    after_task: afterTask,
-    after_any: afterAny ? JSON.stringify(afterAny) : null,
-    origin: req.originWorkspaceId ?? null,
-    priority: req.priority ?? DEFAULT_PRIORITY,
-    machine_needs: setting ? JSON.stringify(setting) : null,
-  });
+  // The row and the piece claim stand or fall together.
+  db.transaction(() => {
+    db.prepare(
+      `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, plan_only, started_by, parent_session_id, started_by_device, started_via, view, agent_type, base_branch,
+         host_id, after_task, after_any, origin_workspace_id, priority, machine_needs, position)
+       VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @plan_only, @started_by, @parent_session_id, @started_by_device, @started_via, @view, @agent_type, @base_branch,
+         @host_id, @after_task, @after_any, @origin, @priority, @machine_needs,
+         (SELECT COALESCE(MAX(position), 0) + 1 FROM task_queue))`
+    ).run({
+      id,
+      project_id: project.id,
+      prompt: req.prompt.trim(),
+      name: req.name?.trim() || null,
+      model: typeof req.model === "string" ? req.model || null : null,
+      model_overrides:
+        req.model && typeof req.model === "object"
+          ? JSON.stringify(req.model)
+          : null,
+      plan: req.plan === undefined ? null : req.plan ? 1 : 0,
+      plan_reason: req.planReason?.trim() || null,
+      plan_only: req.planOnly ? 1 : null,
+      started_by: req.startedBy ?? null,
+      parent_session_id: req.parentSessionId ?? null,
+      started_by_device: req.startedByDevice ?? null,
+      started_via: req.startedVia,
+      view: req.view ?? null,
+      agent_type: req.agent ?? null,
+      base_branch: req.baseBranch || null,
+      host_id: req.hostId || null,
+      after_task: afterTask,
+      after_any: afterAny ? JSON.stringify(afterAny) : null,
+      origin: req.originWorkspaceId ?? null,
+      priority: req.priority ?? DEFAULT_PRIORITY,
+      machine_needs: setting ? JSON.stringify(setting) : null,
+    });
+    if (req.pieceId) claimPiece(req.pieceId, id);
+  })();
   tickQueueSoon();
   return queuedView(id)!;
 }
@@ -729,6 +746,10 @@ async function startRow(
     planReason: r.plan_reason,
     planOnly: !!r.plan_only,
     startedBy: r.started_by,
+    parentSessionId: r.parent_session_id,
+    startedByDevice: r.started_by_device,
+    startedVia: (r.started_via ??
+      (r.started_by ? "session" : "person")) as StartVia,
     view: r.view ?? undefined,
     agent: (r.agent_type as AgentType | null) ?? undefined,
     baseBranch: r.base_branch ?? undefined,
@@ -1022,7 +1043,9 @@ export async function tickOnce(now = Date.now()): Promise<"stale" | void> {
     )) {
       const r = rows.find((x) => x.id === c.id)!;
       const options = (peers.get(r.project_id) ?? []).filter(
-        (p) => !taken.has(p.hostId) && (!r.started_by || p.holds !== false)
+        (p) =>
+          !taken.has(p.hostId) &&
+          (!orchestratorOf(r.started_by) || p.holds !== false)
       );
       const spot = place(c, home, options, built.get(c.id)!.needs, now);
       if (!spot) continue;

package/lib/tasks/remote.ts

@@ -18,6 +18,7 @@ import { projectRef } from "./project-ref";
 import { orchestratedStart } from "./held";
 import type { TaskStatus } from "./state";
 import type { TaskView } from "./index";
+import { orchestratorOf } from "./starter";
 
 // What this machine's task API does, for another machine deciding whether
 // it can trust it with a pinned merge or a move; keyed-start: a session
@@ -140,7 +141,8 @@ export async function startRemoteTask(
   }
 ): Promise<Session> {
   const link = requireHostLink(hostId);
-  const { startedBy, ...rest } = opts;
+  const { startedBy: by, ...rest } = opts;
+  const startedBy = orchestratorOf(by);
   if (startedBy)
     await requireCapability(
       link,

package/lib/tasks/starter.ts

@@ -0,0 +1,124 @@
+// Who started a task and how. started_by is the session that started it (the
+// calling task, chat or orchestrator; null for a person), parent_session_id
+// the session it came from, started_via how it began.
+
+import path from "path";
+import { db } from "../db";
+
+export type StartVia =
+  | "session"
+  | "orchestrator"
+  | "person"
+  | "plan"
+  | "schedule"
+  | "recipe"
+  | "stack"
+  | "remote";
+
+export interface Starter {
+  startedBy: string | null;
+  parentSessionId: string | null;
+  startedVia: StartVia;
+  startedByDevice?: string | null;
+}
+
+export const PERSON: Starter = {
+  startedBy: null,
+  parentSessionId: null,
+  startedVia: "person",
+};
+
+export const personStarter = (device?: string | null): Starter => ({
+  ...PERSON,
+  startedByDevice: device ?? null,
+});
+
+interface Caller {
+  id: string;
+  role: string | null;
+}
+
+// The session making the call: `from` when it names a real session, else the
+// one whose worktree holds `cwd`. A project folder is shared by many
+// sessions, so only a worktree identifies one, and only a task's: a cwd
+// outside every known task worktree names nobody. Remaining trust: any local
+// process can still name a task by its id or its worktree path, exactly as
+// it could name one in `from`; this records who asked, it grants nothing
+// (a piece it claims is that task's own plan's).
+export function callerSession(input: {
+  from?: unknown;
+  cwd?: unknown;
+}): Caller | null {
+  if (typeof input.from === "string" && input.from) {
+    const row = db
+      .prepare(`SELECT id, role FROM sessions WHERE id = ?`)
+      .get(input.from) as Caller | undefined;
+    if (row) return row;
+  }
+  if (typeof input.cwd !== "string" || !path.isAbsolute(input.cwd)) return null;
+  const cwd = path.resolve(input.cwd);
+  const rows = db
+    .prepare(
+      `SELECT id, role, worktree_path FROM sessions
+       WHERE worktree_path IS NOT NULL AND archived_at IS NULL
+         AND task_status IS NOT NULL
+         AND (host_id IS NULL OR host_id = 'local')`
+    )
+    .all() as (Caller & { worktree_path: string })[];
+  let best: (Caller & { worktree_path: string }) | null = null;
+  for (const r of rows) {
+    const wt = path.resolve(r.worktree_path);
+    if (
+      (cwd === wt || cwd.startsWith(wt + path.sep)) &&
+      (!best || wt.length > best.worktree_path.length)
+    )
+      best = r;
+  }
+  return best;
+}
+
+export function starterOf(
+  caller: Caller | null,
+  device?: string | null
+): Starter {
+  if (!caller) return personStarter(device);
+  return {
+    startedBy: caller.id,
+    parentSessionId: caller.id,
+    startedVia: caller.role === "orchestrator" ? "orchestrator" : "session",
+  };
+}
+
+// The orchestrator that owns a session's work: follows started_by up to the
+// first orchestrator, null when the chain ends at a person. It gives up after
+// 6 hops (a deeper chain, or a cycle, counts as no orchestrator), so a bad
+// row can never loop it.
+export function orchestratorOf(startedBy: string | null | undefined) {
+  const seen = new Set<string>();
+  let id = startedBy ?? null;
+  for (let hops = 0; id && hops < 6 && !seen.has(id); hops++) {
+    seen.add(id);
+    const row = db
+      .prepare(`SELECT role, started_by FROM sessions WHERE id = ?`)
+      .get(id) as
+      | { role: string | null; started_by: string | null }
+      | undefined;
+    if (!row) return null;
+    if (row.role === "orchestrator") return id;
+    id = row.started_by;
+  }
+  return null;
+}
+
+export function recordStart(id: string, s: Starter): void {
+  db.prepare(
+    `UPDATE sessions SET started_by = ?, parent_session_id = (SELECT id FROM sessions WHERE id = ?), started_via = ?,
+       started_by_device = COALESCE(?, started_by_device) WHERE id = ?`
+  ).run(
+    s.startedBy,
+    s.parentSessionId,
+    s.startedVia,
+    s.startedByDevice ?? null,
+    id
+  );
+}

package/lib/usage/calls.ts

@@ -6,7 +6,8 @@
  */
 
 import { db } from "../db";
-import { ANTHROPIC, sessionRole } from "../models/roles";
+import { ANTHROPIC } from "../models/roles";
+import { sessionRole } from "../models/session-role";
 import { ctxOf, weighted, type TokenRow } from "./weights";
 import type { CallKind, CallRow, CallSource, CallUsage } from "./types";
 

package/lib/usage/turns.ts

@@ -8,7 +8,8 @@ import { db, type Session } from "../db";
 import type { UsageTotals } from "../chat/events";
 import { totalTokens, turnDelta } from "../chat/context";
 import { readUsage } from "../orchestrator/usage";
-import { ANTHROPIC, sessionRole } from "../models/roles";
+import { ANTHROPIC } from "../models/roles";
+import { sessionRole } from "../models/session-role";
 
 // Where a worker's totals start: a resumed conversation continues from the
 // totals its transcript saved, which the last worker stored; a new one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.597",
+  "version": "0.3.600",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"