baton-issue-tracker 1.6.0 → 1.8.0

package/drizzle/0002_breezy_wiccan.sql

@@ -0,0 +1,10 @@
+CREATE TABLE `agents` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`type` text NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `agents_name_unique` ON `agents` (`name`);--> statement-breakpoint
+ALTER TABLE `activity` ADD `actor_id` integer REFERENCES agents(id);--> statement-breakpoint
+ALTER TABLE `issues` ADD `assignee_id` integer REFERENCES agents(id);--> statement-breakpoint
+ALTER TABLE `issues` DROP COLUMN `assignees`;

package/drizzle/meta/0002_snapshot.json

@@ -0,0 +1,229 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "d89cefa6-9c90-4882-8fab-f6322fd1f45e",
+  "prevId": "af5467aa-0757-4c91-8afb-c6f0202dd90c",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "log_id": {
+          "name": "log_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "issue_id": {
+          "name": "issue_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actor_id": {
+          "name": "actor_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "CURRENT_TIMESTAMP"
+        },
+        "action": {
+          "name": "action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "details": {
+          "name": "details",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "activity_actor_id_agents_id_fk": {
+          "name": "activity_actor_id_agents_id_fk",
+          "tableFrom": "activity",
+          "tableTo": "agents",
+          "columnsFrom": [
+            "actor_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {
+        "activity_action_check": {
+          "name": "activity_action_check",
+          "value": "\"activity\".\"action\" IN ('state_change', 'priority_change', 'edit', 'read', 'creation', 'deletion', 'rejection')"
+        }
+      }
+    },
+    "agents": {
+      "name": "agents",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "agents_name_unique": {
+          "name": "agents_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "issues": {
+      "name": "issues",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "CURRENT_TIMESTAMP"
+        },
+        "last_updated": {
+          "name": "last_updated",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "CURRENT_TIMESTAMP"
+        },
+        "attempt_num": {
+          "name": "attempt_num",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'PENDING'"
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'Open'"
+        },
+        "priority": {
+          "name": "priority",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": "'Low'"
+        },
+        "token_limit": {
+          "name": "token_limit",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "assignee_id": {
+          "name": "assignee_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "issues_assignee_id_agents_id_fk": {
+          "name": "issues_assignee_id_agents_id_fk",
+          "tableFrom": "issues",
+          "tableTo": "agents",
+          "columnsFrom": [
+            "assignee_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1780114722528,
       "tag": "0001_salty_luke_cage",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1780293597234,
+      "tag": "0002_breezy_wiccan",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baton-issue-tracker",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "A CLI issue tracker for AI agents",
   "type": "module",
   "bin": {

package/source/cli.js

@@ -24,8 +24,12 @@ import { run as runSearch } from './commands/search.js';
 import { run as runList } from './commands/list.js';
 import { run as runCreate } from './commands/create.js'
 import { run as runUpdate } from './commands/update.js';
+import { run as runDelete } from './commands/delete.js';
 import { run as runPriority } from './commands/priority.js';
 import { run as runLog } from './commands/log.js';
+import { run as runRegister } from './commands/register.js';
+
+import { authenticateContext } from './services/authService.js';
 
 const HELP = `baton — AI agent issue tracker CLI
 
@@ -34,6 +38,7 @@ Usage:
 
 Commands:
   init     Initialize storage and seed issues from product specs
+  register Register a new AI agent or human user
   next     Work on the highest-priority open issue
   loop     Run the agent autonomously for multiple steps
   status   Show issue counts and overall progress
@@ -44,6 +49,7 @@ Commands:
   approve  Move an issue from in-review to closed
   priority Set an issue's priority level
   update   Updates an issue's specified fields
+  delete   Deletes an issue
   log      Show activity history for an issue
 
 Options:
@@ -52,6 +58,8 @@ Options:
   init --json                     Output as JSON (for AI agents)
   init <path>                     Same as --specs <path> (positional)
   Default specs: docs/specs/project-requirements.md
+  register --name <name>          Name of the agent or user
+  register --type <type>          agent | human (default: agent)
   loop --steps <n>                Number of autonomous steps (alias: -n)
   loop -n <n>
   loop --json                     Output as JSON (for AI agents)
@@ -77,6 +85,7 @@ Options:
   update --status <s>             open | in-progress | closed
   update --priority <level>       low | medium | high
   update --json                   Output as JSON (for AI agents)
+  delete <id> [--yes]
   log <id> [--json]
 
 Examples:
@@ -84,6 +93,7 @@ Examples:
   baton init --specs ./my-specs.md
   baton init ./my-specs.md
   baton init --force
+  baton register --name claude-dev --type agent
   baton next
   baton loop --steps 5
   baton status
@@ -109,8 +119,18 @@ Examples:
 async function main() {
   const [, , command, ...args] = process.argv;
 
+  if (!command || command === 'help' || wantsHelp(args) || command === '--help') {
+    console.log(HELP);
+    process.exit(command ? 0 : 1);
+    return;
+  }
+
+  // Authenticate the user and context before executing any command.
+  authenticateContext(command);
+
   const handlers = {
     init: () => runInit(args),
+    register: () => runRegister(args),
     next: () => runNext(args),
     loop: () => runLoop(args),
     status: () => runStatus(args),
@@ -121,15 +141,10 @@ async function main() {
     priority: () => runPriority(args),
     create: () => runCreate(args),
     update: () => runUpdate(args),
+    delete: () => runDelete(args),
     log: () => runLog(args),
   };
 
-  if (!command || command === 'help' || command === '--help') {
-    console.log(HELP);
-    process.exit(command ? 0 : 1);
-    return;
-  }
-
   const handler = handlers[command];
   if (!handler) {
     if (wantsHelp(args)) {

package/source/commands/delete.js

@@ -0,0 +1,99 @@
+// delete.js
+// supports deleting an issue.
+// 
+// AI was used to modify this file to support JSON outputs.
+// 
+// Usage:
+//   baton delete <id> [--yes] [--json]
+//
+// Options:
+//   --yes        Skip confirmation prompt
+//   --json       Output in JSON format
+//   -h, --help   Show this help
+//
+// Examples:
+//   baton delete 4
+//   baton delete 4 --yes
+
+import { deleteIssue, getIssue } from '../services/issuesService.js';
+import { hasFlag, wantsHelp, renderOutput, renderError } from '../util.js';
+import { confirm } from '@inquirer/prompts';
+
+const USAGE = "Usage: baton delete <id> [options]\n\nOptions:\n  --yes        Skip confirmation prompt\n  --json       Output in JSON format\n  -h, --help   Show this help";
+
+/**
+ * Deletes an issue for a specified ID.
+ * 
+ * @param {string[]} args - The command line arguments
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run(args) {
+    const isJson = hasFlag(args, '--json');
+
+    // (0) Help check
+    if (wantsHelp(args)) {
+        console.log(USAGE);
+        return 0;
+    }
+
+    // (1) Parse arguments
+    const idArgs = args.filter(arg => !arg.startsWith('-'));
+    if (idArgs.length === 0) {
+        renderError(isJson, `No ID provided.\n${USAGE}`, 'MISSING_ID');
+        return 1;
+    }
+
+    const id = Number(idArgs[0]);
+    if (!Number.isInteger(id)) {
+        renderError(isJson, `Invalid ID "${idArgs[0]}". ID must be an integer.`, 'INVALID_ID');
+        return 1;
+    }
+
+    const isYes = hasFlag(args, "--yes");
+
+    try {
+        // (2) Check if issue exists before confirming
+        try {
+            await getIssue(id);
+        } catch (error) {
+            if (error.message.includes("not found")) {
+                renderError(isJson, error.message, 'NOT_FOUND');
+            } else {
+                renderError(isJson, error.message);
+            }
+            return 1;
+        }
+
+        // (3) Confirmation prompt
+        let confirmed = isYes;
+        if (!confirmed && !isJson) { // Only prompt if not JSON and not --yes
+            try {
+                confirmed = await confirm({ message: `Are you sure you want to delete issue #${id}?`, default: false });
+            } catch {
+                return 1;
+            }
+        } else if (!confirmed && isJson) {
+            // In JSON mode, do not prompt. If --yes is missing, we fail or assume no.
+            renderError(isJson, "Confirmation required. Use --yes to confirm deletion in JSON mode.", 'CONFIRMATION_REQUIRED');
+            return 1;
+        }
+
+        if (!confirmed) {
+            console.log("Deletion cancelled.");
+            return 0;
+        }
+
+        // (4) Execution
+        await deleteIssue(id);
+        
+        const envelope = { status: 'success', id: id, message: `Issue #${id} deleted successfully.` };
+        renderOutput(isJson, envelope, () => {
+            console.log(`Issue #${id} deleted successfully.`);
+        });
+        
+        return 0;
+    } catch (error) {
+        renderError(isJson, error.message);
+        return 1;
+    }
+}

package/source/commands/next.js

@@ -6,7 +6,7 @@
 import {
   isTrackerReady,
   selectNextIssue,
-  workOnIssue,
+  claimIssue,
 } from '../services/issuesService.js';
 import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializeIssue } from '../util.js';
 
@@ -14,7 +14,7 @@ import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializ
  * Moves the AI agent to work on the next issue. 
  * Checks if the tracker is ready and if there are any open issues.
  * Prompts user to initialize the tracker if it is not ready.
- * Stats are updated on the issue through workOnIssue function from init.js.
+ * Stats are updated on the issue through claimIssue function from init.js.
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args = []) {
@@ -33,7 +33,7 @@ export async function run(args = []) {
     return 0;
   }
 
-  const updated = workOnIssue(issue.id);
+  const updated = claimIssue(issue.id);
   const envelope = { status: 'success', issue: serializeIssue(updated) };
 
   renderOutput(isJson, envelope, () => {

package/source/commands/register.js

@@ -0,0 +1,68 @@
+// register.js
+// AI was consulted for some portions of this file.
+// register command which allows the user to register a new AI agent or human
+// Usage: baton register --name <name> [--type <type>] [--json]
+//
+// Options:
+//  --name <n>        Name of the agent or human (required)
+//  --type <t>        Type: agent | human (default: agent)
+//  --json            Output as JSON (for AI agents)
+//  -h, --help        Show this help
+
+import { registerAgent } from '../services/agentsService.js';
+import {
+  getFlagValue,
+  hasFlag,
+  renderOutput,
+} from '../util.js';
+
+/**
+ * Registers a new agent or human user
+ * @param {string[]} args - The command line arguments
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error
+ */
+export async function run(args) {
+    const isJson = hasFlag(args, '--json');
+    const validFlags = ['--name', '--type', '--json'];
+    
+    // Check if user misspelled a flag
+    for (const arg of args) {
+        if (arg.startsWith('--')) {
+            if (!validFlags.includes(arg)) {
+                throw new Error(`Unknown flag provided: ${arg}. \nFlags: --name <n>, --type <t>, --json`);
+            }
+        }
+    }
+
+    try {
+        const name = getFlagValue(args, '--name');
+        const type = getFlagValue(args, '--type') || 'agent';
+
+        if (!name) {
+            throw new Error("Missing required flag: --name <name>");
+        }
+
+        if (type !== 'agent' && type !== 'human') {
+            throw new Error(`Invalid type "${type}". Must be 'agent' or 'human'.`);
+        }
+
+        const agent = registerAgent(name, type);
+        const envelope = { status: 'success', agent };
+
+        renderOutput(isJson, envelope, (data) => {
+            console.log(`\nSuccessfully registered ${data.agent.type}: "${data.agent.name}" (ID: ${data.agent.id})\n`);
+        });
+
+        return 0;
+    } catch (error) {
+        if (error.message.includes('UNIQUE constraint failed')) {
+            console.error(`Error: An agent or user with the name "${getFlagValue(args, '--name')}" is already registered.`);
+        } else if (error.message.includes('Missing required') || error.message.includes('Invalid type')) {
+            console.error(`Usage Error: ${error.message}`);
+        } else {
+            console.error("Error: Failed to register agent.");
+            console.error(error.message);
+        }
+        return 1;
+    }
+}

package/source/models/activityLog.js

@@ -12,11 +12,13 @@ export class ActivityLog {
   constructor({
     logId     = null,
     issueId,
+    actorId   = null,
     action,
     createdAt = new Date().toISOString(),
   } = {}) {
     this.logId     = logId;
     this.issueId   = issueId;
+    this.actorId   = actorId;
     this.action    = action;
     this.createdAt = createdAt;
   }

package/source/models/agents.js

@@ -0,0 +1,37 @@
+export const AgentType = Object.freeze({
+  AGENT: "agent",
+  HUMAN: "human"
+});
+
+export class Agent {
+  constructor({
+    // User fields
+    name      = "Unnamed",
+    type      = AgentType.AGENT,
+    // Auto-generated fields
+    id        = 0,
+    createdAt = new Date().toISOString(),
+  } = {}) {
+    this.name      = name;
+    this.type      = type;
+    this.id        = id;
+  }
+
+  /**
+   * Validates the agent fields based on project business rules.
+   * @returns {{isValid: boolean, errors: string[]}} boolean and an array of errors
+   */
+  validate() {
+    const errors = [];
+
+    if (!this.name || typeof this.name !== "string" || this.name.trim() === "") {
+        errors.push("Name cannot be empty");
+    }
+
+    if (!Object.values(AgentType).includes(this.type)) {
+      errors.push(`Invalid type "${this.type}". Must be one of: ${Object.values(AgentType).join(", ")}`);
+    }
+
+    return { isValid: errors.length === 0, errors: errors };
+  }
+}

package/source/models/issue.js

@@ -20,7 +20,7 @@ export class Issue {
     tokenLimit  = null,
     description = null,
     lastUpdated = new Date().toISOString(),
-    assignees = null,
+    assigneeId  = null,
     // Auto-generated fields
     id          = 0,
     createdAt  = new Date().toISOString(),
@@ -32,7 +32,7 @@ export class Issue {
     this.tokenLimit  = tokenLimit;
     this.description = description;
     this.lastUpdated = lastUpdated;
-    this.assignees = assignees;
+    this.assigneeId  = assigneeId;
     this.id          = id;
     this.createdAt  = createdAt;
     this.attemptNum = attemptNum;
@@ -68,5 +68,3 @@ export class Issue {
     return {isValid: errors.length == 0, errors: errors}
   }
 }
-
-

package/source/models/schema.js

@@ -3,6 +3,12 @@ import { sql } from "drizzle-orm";
 import { Status, Priority } from "./issue.js";
 import { Action } from "./activityLog.js";
 
+export const agentsTable = sqliteTable("agents", {
+  id:   int().primaryKey({ autoIncrement: true }),
+  name: text().notNull().unique(),
+  type: text({ enum: ['agent', 'human'] }).notNull(),
+});
+
 export const issuesTable = sqliteTable("issues", {
   id:          int().primaryKey({ autoIncrement: true }),
   createdAt:   text("created_at").notNull().default(sql`CURRENT_TIMESTAMP`),
@@ -13,7 +19,7 @@ export const issuesTable = sqliteTable("issues", {
   priority:    text({ enum: Object.values(Priority) }).default(Priority.LOW),
   tokenLimit:  int("token_limit"),
   description: text(),
-  assignees:   text({mode: "json"}).default(sql`'[]'`),
+  assigneeId:  int("assignee_id").references(() => agentsTable.id),
 });
 
 export const activityTable = sqliteTable(
@@ -21,6 +27,7 @@ export const activityTable = sqliteTable(
   {
     logId:     int("log_id").primaryKey({ autoIncrement: true }),
     issueId:   int("issue_id"),
+    actorId:   int("actor_id").references(() => agentsTable.id),
     createdAt: text("created_at").notNull().default(sql`CURRENT_TIMESTAMP`),
     action:    text({ enum: Object.values(Action) }).notNull(),
     details:   text(),
@@ -46,8 +53,8 @@ export const issueSchema = {
     tokenLimit: { flag: '--token-limit', type: 'number' },
     priority:   { flag: '--priority', type: 'enum', values: Object.values(Priority) },
     description:{ flag: '--description', type: 'string' },
-    //assignees:   { flag: '--assignees', type: 'json'},
+    assigneeId: { flag: '--assignee-id', type: 'number'},
     // Pagination options 
     limit:      { flag: '--limit', type: 'number' },
-    offset:       { flag: '--offset', type: 'number' }
+    offset:     { flag: '--offset', type: 'number' }
 };

package/source/services/agentsService.js

@@ -0,0 +1,42 @@
+import { getDB } from '../db/index.js';
+import { eq } from "drizzle-orm";
+import { agentsTable } from "../models/schema.js";
+import { Agent } from '../models/agents.js';
+
+/**
+ * Registers a new agent in the database.
+ * @param {string} name 
+ * @param {string} type 
+ * @returns {Agent|null}
+ */
+export function registerAgent(name, type) {
+  const db = getDB();
+  const result = db.insert(agentsTable)
+    .values({ name: name, type: type })
+    .returning({ id: agentsTable.id })
+    .get();
+  
+  const row = db.select().from(agentsTable).where(eq(agentsTable.id, result.id)).get();
+  
+  if (row) {
+    return new Agent(row);
+  } else {
+    return null;
+  }
+}
+
+/**
+ * Retrieves an agent by their unique name.
+ * @param {string} name 
+ * @returns {Agent|null}
+ */
+export function getAgentByName(name) {
+  const db = getDB();
+  const row = db.select().from(agentsTable).where(eq(agentsTable.name, name)).get();
+  
+  if (row) {
+    return new Agent(row);
+  } else {
+    return null;
+  }
+}

package/source/services/authService.js

@@ -0,0 +1,44 @@
+import os from 'os';
+import { getAgentByName } from './agentsService.js';
+import { setActiveActor } from './issuesService.js';
+
+/**
+ * Authenticates the current execution context.
+ * Looks for BATON_AGENT in the environment, falling back to the OS username.
+ * If the agent/user is registered, it sets them as the active actor for this session.
+ * If not, it terminates the process with a helpful error message.
+ * @param {string} command - The command being executed
+ */
+export function authenticateContext(command) {
+  // Commands that don't require an active agent signed in
+  const exemptCommands = ['init', 'register', 'help'];
+  if (exemptCommands.includes(command)) {
+    return;
+  }
+
+  // Identify who is running the CLI
+  const activeName = process.env.BATON_AGENT || os.userInfo().username;
+  
+  try {
+    // Look them up in the database
+    const agent = getAgentByName(activeName);
+
+    if (!agent) {
+      console.error(`Error: Agent/User "${activeName}" is not registered in this Baton tracker.`);
+      console.error(`Please run 'baton register --name "${activeName}" --type "human"' (or "agent") first.`);
+      process.exit(1);
+    }
+
+    // Set the global state for the remainder of this command's lifecycle
+    setActiveActor(agent.id);
+  } catch (error) {
+    // Gracefully handle the scenario where the database hasn't been initialized yet
+    if (error.message && error.message.includes('no such table: agents')) {
+      console.error("Error: Tracker is not initialized. Please run 'baton init' first.");
+      process.exit(1);
+    }
+    
+    // Rethrow if it's a completely different error
+    throw error;
+  }
+}

package/source/services/issuesService.js

@@ -8,6 +8,17 @@ import {
 } from "../models/issue.js";
 import { ActivityLog, Action } from '../models/activityLog.js';
 
+// Internal variable to hold the active agent's ID for logging purposes. Set via setActiveActor() during authentication.
+let currentActorId = null;
+
+/**
+ * Sets the active actor ID for logging purposes.
+ * @param {number} id - The ID of the active actor.
+ */
+export function setActiveActor(id) {
+    currentActorId = id;
+}
+
 /**
  * Internal helper to log actions.
  * @private
@@ -18,7 +29,7 @@ import { ActivityLog, Action } from '../models/activityLog.js';
  */
 function logActivity(db, issueId, action, details = null) {
   db.insert(activityTable)
-    .values({ issueId, action, details })
+    .values({ issueId, action, details, actorId: currentActorId })
     .run();
 }
 
@@ -65,6 +76,7 @@ function findById(db, id) {
  * @property {string} [priority] - The priority level.
  * @property {number} [tokenLimit] - The maximum token limit for the issue.
  * @property {string} [description] - The detailed description of the issue.
+ * @property {number} [assigneeId] - The assigned agent ID.
  */
 
 /**
@@ -78,6 +90,7 @@ export function createIssue({
   priority,
   tokenLimit,
   description,
+  assigneeId,
 } = {}) {
 
   const db = getDB();
@@ -87,6 +100,7 @@ export function createIssue({
       priority: priority ?? Priority.LOW,
       tokenLimit: tokenLimit ?? null,
       description: description ?? null,
+      assigneeId: assigneeId ?? null,
     })
     .returning({ id: issuesTable.id })
     .get();
@@ -116,6 +130,7 @@ export function getIssue(id) {
  * @property {string} [priority] - Filter issues by their priority level.
  * @property {number} [limit] - Maximum number of issues to return.
  * @property {number} [offset] - Pagination offset.
+ * @property {number} [assigneeId] - Filter by assigned agent.
  */
 
 /**
@@ -123,7 +138,7 @@ export function getIssue(id) {
  * @param {ListIssuesOptions} options - Filtering and pagination options.
  * @returns {Issue[]}
  */
-export async function listIssues({ status, priority, limit, offset } = {}) {
+export async function listIssues({ status, priority, limit, offset, assigneeId } = {}) {
   const db = getDB();
   const filters = [];
 
@@ -136,6 +151,10 @@ export async function listIssues({ status, priority, limit, offset } = {}) {
     filters.push(sql`${issuesTable.priority} COLLATE NOCASE = ${priority}`);
   }
 
+  if (assigneeId !== undefined) {
+    filters.push(eq(issuesTable.assigneeId, assigneeId));
+  }
+
   // set defaults if limit or offset is NULL
   const limitVal = limit ?? 50;
   const offsetVal = offset ?? 0;
@@ -180,6 +199,7 @@ export function searchIssues(query) {
  * @property {number} [tokenLimit] - The updated token limit.
  * @property {string} [status] - The updated status.
  * @property {string} [priority] - The updated priority.
+ * @property {number} [assigneeId] - The updated assignee ID.
  */
 
 /**
@@ -190,13 +210,14 @@ export function searchIssues(query) {
  * @param {UpdateIssueFields} fields - The fields to update.
  * @returns {Issue}
  */
-export function updateIssue(id, oldIssue, { title, description, tokenLimit, status, priority } = {}) {
+export function updateIssue(id, oldIssue, { title, description, tokenLimit, status, priority, assigneeId } = {}) {
   const db = getDB();
   const updates = {};
 
   if (title !== undefined) updates.title = title;
   if (description !== undefined) updates.description = description;
   if (tokenLimit !== undefined) updates.tokenLimit = tokenLimit;
+  if (assigneeId !== undefined) updates.assigneeId = assigneeId;
 
   // Normalize status argument
   if (status !== undefined) {
@@ -350,12 +371,12 @@ export function getRecentActivity({ limit = 20 } = {}) {
   return db.select().from(activityTable).orderBy(sql`${activityTable.logId} DESC`).limit(limit).all();
 }
 // =============================================================================
-// Tracker operations (CLI: init / next / status / loop)
+// Tracker operations (CLI: init / next / status / claim)
 // To be edited later if needed.
 // =============================================================================
 
 /**
- * True when both `issues` and `activity` tables exist (matches initDB schema).
+ * True when both `issues`, `activity`, and `agents` tables exist.
  * @returns {boolean}
  */
 export function isTrackerReady() {
@@ -365,9 +386,9 @@ export function isTrackerReady() {
     const row = db.get(sql`
         SELECT COUNT(*) AS table_count
         FROM sqlite_master
-        WHERE type = 'table' AND name IN ('issues', 'activity')
+        WHERE type = 'table' AND name IN ('issues', 'activity', 'agents')
       `);
-    return (row?.table_count ?? 0) === 2;
+    return (row?.table_count ?? 0) === 3;
   } catch (error) {
     return false;
   }
@@ -425,12 +446,11 @@ export function selectNextIssue() {
 }
 
 /**
- * Mark an issue in-progress, increment attempts, and log activity (atomic).
- * Uses existing `findById` / `logActivity` from above; does not modify lines 1–187.
+ * Mark an issue in-progress, assign it to the current actor, increment attempts, and log activity.
  * @param {number} issueId
  * @returns {object}
  */
-export function workOnIssue(issueId) {
+export function claimIssue(issueId) {
   const db = getDB();
   const issue = findById(db, issueId);
 
@@ -444,6 +464,7 @@ export function workOnIssue(issueId) {
     tx.update(issuesTable)
       .set({ 
         status: Status.IN_PROGRESS,
+        assigneeId: currentActorId, 
         attemptNum: sql`${issuesTable.attemptNum} + 1` 
       })
       .where(eq(issuesTable.id, issueId))
@@ -453,14 +474,14 @@ export function workOnIssue(issueId) {
       tx,
       issueId,
       Action.STATE_CHANGE,
-      `Status changed from ${issue.status} to ${Status.IN_PROGRESS}`,
+      `Status changed from ${issue.status} to ${Status.IN_PROGRESS}`
     );
     
     logActivity(
       tx,
       issueId,
       Action.EDIT,
-      `Agent attempt #${issue.attemptNum + 1} on issue #${issueId}`,
+      `Agent attempt #${issue.attemptNum + 1} on issue #${issueId}`
     );
   });