fix(api): enforce one leader per runtime

saltbo · saltbo · commit d3f533e2ebec · 2026-04-14T15:35:04.000-04:00
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ Agent Kanban is that workspace. Every agent gets an Ed25519 identity — a crypt
 
 ```
 Human talks to an agent runtime (Claude Code, Codex, Gemini CLI)
-  → Agent auto-registers as a leader via `ak` CLI
+  → Leader agent uses `ak` with its own identity
   → Leader breaks the goal into tasks and assigns to workers
   → Daemon dispatches workers, each in its own worktree
   → Workers claim, implement, and open PRs
@@ -116,7 +116,15 @@ The `-g` flag installs globally so the skills are available across all your repo
 
 ### 4. Use your agent runtime
 
-Open any agent runtime (Claude Code, Codex, Gemini CLI) in a repo. The first `ak` call auto-registers the runtime as a leader agent with its own Ed25519 identity. Use the installed skills to manage your AI team:
+Open any agent runtime (Claude Code, Codex, Gemini CLI) in a repo.
+
+A leader agent can create its own identity:
+
+```bash
+ak identity create --username alex --name "Alex Chen"
+```
+
+After that, `ak` reuses that leader identity across sessions for the same runtime. Then use the installed skills to manage your AI team:
 
 - **`/ak-plan v1.0 <goals>`** — analyze the codebase, create a board with tasks and dependencies, assign to agents
 - **`/ak-task fix the login redirect bug`** — create a single task, assign it, monitor → review → merge
@@ -127,7 +135,8 @@ The leader creates and assigns tasks; the daemon picks them up and dispatches wo
 
 Every agent gets a unique cryptographic identity:
 
-- **Ed25519 keypair** — generated per agent spawn
+- **Leader identity** — created explicitly once per runtime, then reused across sessions
+- **Ed25519 keypair** — generated per agent session
 - **Fingerprint** — derived from the public key
 - **Identicon** — visual representation of the fingerprint
 - **JWT auth** — agents sign their own tokens, verified server-side
@@ -178,6 +187,10 @@ Task Lifecycle:
   task cancel <id>         Cancel a task
   task release <id>        Release back to todo
 
+Identity:
+  identity create          Create a leader identity for the current runtime
+  whoami                   Show the current runtime's agent identity
+
 Output:
   -o json|yaml|wide        Output format (default: text table)
 ```
diff --git a/apps/web/migrations/0017_unique_leader_per_runtime.sql b/apps/web/migrations/0017_unique_leader_per_runtime.sql
@@ -0,0 +1,3 @@
+-- Enforce a single leader per owner/runtime pair while allowing many workers.
+CREATE UNIQUE INDEX idx_agents_owner_runtime_leader ON agents(owner_id, runtime)
+  WHERE kind = 'leader' AND runtime IS NOT NULL;
diff --git a/apps/web/server/routes.ts b/apps/web/server/routes.ts
@@ -421,6 +421,14 @@ api.post("/api/agents", async (c) => {
   // Validate username uniqueness before GPG mutation
   const taken = await c.env.DB.prepare("SELECT 1 FROM agents WHERE username = ?").bind(body.username).first();
   if (taken) throw new HTTPException(409, { message: `Username "${body.username}" is already taken` });
+  if (body.kind === "leader") {
+    const existingLeader = await c.env.DB.prepare("SELECT 1 FROM agents WHERE owner_id = ? AND runtime = ? AND kind = 'leader'")
+      .bind(ownerId, body.runtime)
+      .first();
+    if (existingLeader) {
+      throw new HTTPException(409, { message: `Leader agent for runtime "${body.runtime}" already exists` });
+    }
+  }
 
   // GPG subkey — its Ed25519 material becomes the agent's unified key
   const email = agentEmail(body.username);
diff --git a/docs/designs/agent-kanban-v1.md b/docs/designs/agent-kanban-v1.md
@@ -211,15 +211,15 @@ The skill must explicitly document that agents can **create tasks** — not just
 | Shared types | Proper workspace package with build step | Works with CF bundler + npm publish |
 | Skill location | `packages/skill/` in pnpm workspace | Version-controlled with CLI, install script copies to `~/.claude/skills/` |
 | Claim atomicity | `db.batch()` for atomic claim | Prevents race condition on concurrent /claim |
-| Agent identity | API key = Machine (not Agent). Agents auto-register on claim. | One key per computer, zero per-agent config. Forward-compatible with v2 roles. |
+| Agent identity | API key = Machine (not Agent). Leader identity is created explicitly, then reused by runtime. | One key per computer with stable per-runtime agent identity. |
 
 ### Identity & Auth Model (revised)
 
-The original design had one API key per agent. Revised to Machine-level auth with auto-registered agent instances.
+The original design had one API key per agent. Revised to Machine-level auth with an explicitly created leader identity per runtime.
 
 **API key = Machine.** One key per computer. Configured once via `agent-kanban config set api-key`. All agents on that machine share the same key.
 
-**Agent = auto-registered on first claim/create.** No pre-registration needed.
+**Leader identity = created explicitly once per runtime.** After that, the CLI reuses the local identity cache and restores the unique server-side leader for that runtime if the local cache is missing.
 
 ```
 api_keys (represents a Machine)
diff --git a/docs/designs/vision.md b/docs/designs/vision.md
@@ -197,21 +197,21 @@ Agent Instance Layer (execution)
 
 ## Identity & Auth Architecture
 
-### v1 (current): Machine-Level Auth + Auto-Registered Agents
+### v1 (current): Machine-Level Auth + Explicit Leader Identity
 
 ```
 api_keys (represents a Machine, not an Agent)
   id, key_hash, name (machine name), created_at
 
-agents (lightweight, auto-registered on claim)
-  id, machine_id → api_keys.id, name (auto-generated), role_id (null), created_at
+agents
+  id, name, username, runtime, kind, created_at
 
 tasks
   assigned_to → agents.id (not api_key name)
   created_by  → agents.id or "human"
 ```
 
-One API key per Machine. One Machine can have many concurrent agent instances. Agent instances are auto-created when they first claim or create a task — zero manual setup.
+One API key per Machine. One Machine can have many concurrent agent instances. Leader identities are created explicitly once per runtime, then reused across sessions. If the local identity cache is missing, the CLI restores the unique server-side leader for that runtime.
 
 ### v2: Add Roles
 
diff --git a/skills/ak-plan/SKILL.md b/skills/ak-plan/SKILL.md
@@ -22,6 +22,18 @@ allowed-tools:
 
 Plan and create a board with tasks — for a new version release or a new product from scratch.
 
+## Identity
+
+This is a leader workflow.
+
+If `ak` says no leader identity exists for the current runtime, create one first:
+
+```bash
+ak identity create --username <username> [--name <name>]
+```
+
+The leader chooses its own username and optional full name.
+
 ## Input
 
 Parse the user's input:
diff --git a/skills/ak-task/SKILL.md b/skills/ak-task/SKILL.md
@@ -19,6 +19,18 @@ allowed-tools:
 
 Create a task, assign it, then monitor → review → reject/complete.
 
+## Identity
+
+This is a leader workflow.
+
+If `ak` says no leader identity exists for the current runtime, create one first:
+
+```bash
+ak identity create --username <username> [--name <name>]
+```
+
+The leader chooses its own username and optional full name.
+
 ## Input
 
 Parse the user's input:
diff --git a/tests/agent-auth.test.ts b/tests/agent-auth.test.ts
@@ -34,6 +34,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/agent-json-fields.test.ts b/tests/agent-json-fields.test.ts
@@ -27,6 +27,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/agent-redesign.test.ts b/tests/agent-redesign.test.ts
@@ -47,6 +47,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/builtin-agents.test.ts b/tests/builtin-agents.test.ts
@@ -36,6 +36,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/cli-agent-jwt.test.ts b/tests/cli-agent-jwt.test.ts
@@ -41,6 +41,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/helpers/db.ts b/tests/helpers/db.ts
@@ -35,6 +35,7 @@ export async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/machine-agent-flow.test.ts b/tests/machine-agent-flow.test.ts
@@ -42,6 +42,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/machine-usage.test.ts b/tests/machine-usage.test.ts
@@ -27,6 +27,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/routes.test.ts b/tests/routes.test.ts
@@ -346,6 +346,18 @@ describe("routes", () => {
     expect(body.username).toBe("username-check-agent");
   });
 
+  it("POST /api/agents rejects a second leader for the same runtime", async () => {
+    const res = await apiRequest(
+      "POST",
+      "/api/agents",
+      { username: "second-routes-leader", name: "Second Routes Leader", runtime: "claude", kind: "leader" },
+      apiKey,
+    );
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as any;
+    expect(body.error.message).toContain('Leader agent for runtime "claude" already exists');
+  });
+
   it("GET /api/agents returns email derived from username", async () => {
     const res = await apiRequest("GET", "/api/agents", undefined, apiKey);
     expect(res.status).toBe(200);
diff --git a/tests/task-dependencies.test.ts b/tests/task-dependencies.test.ts
@@ -35,6 +35,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/task-json-fields.test.ts b/tests/task-json-fields.test.ts
@@ -27,6 +27,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");
diff --git a/tests/task-state-machine.test.ts b/tests/task-state-machine.test.ts
@@ -39,6 +39,7 @@ async function applyMigrations(db: D1Database) {
     "0014_agent_mailbox_token.sql",
     "0015_username_global_unique.sql",
     "0016_task_actions_session_id.sql",
+    "0017_unique_leader_per_runtime.sql",
   ];
   for (const file of files) {
     const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf-8");

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+-- Enforce a single leader per owner/runtime pair while allowing many workers.`
	`2`	`+CREATE UNIQUE INDEX idx_agents_owner_runtime_leader ON agents(owner_id, runtime)`
	`3`	`+ WHERE kind = 'leader' AND runtime IS NOT NULL;`