@mean-weasel/lineage 0.1.3 → 0.1.5

package/dist/cli/lineage-dev.js

@@ -7,9 +7,17 @@ import { dirname as dirname3, join as join5, resolve as resolve3 } from "node:pa
 import { spawn } from "node:child_process";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
+// src/server/agentClaims.ts
+import { createHash as createHash2, randomBytes, timingSafeEqual } from "node:crypto";
+
+// src/server/assetLineageDb.ts
+import { createRequire } from "node:module";
+import { mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+
 // src/server/assetCore.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "node:fs";
-import { dirname as dirname2, join as join4, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -190,19 +198,244 @@ function createS3StorageAdapter(deps) {
   };
 }
 
+// src/server/assetCore.ts
+function isPackageRoot(path) {
+  const packageJson = join3(path, "package.json");
+  if (!existsSync3(packageJson)) return false;
+  try {
+    const packageInfo = JSON.parse(readFileSync2(packageJson, "utf8"));
+    return packageInfo.name === "@mean-weasel/lineage";
+  } catch {
+    return false;
+  }
+}
+function resolveRepoRoot() {
+  const moduleDir = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    process.env.LINEAGE_REPO_ROOT,
+    resolve2(moduleDir, ".."),
+    resolve2(moduleDir, "../.."),
+    process.cwd()
+  ].filter((candidate) => Boolean(candidate));
+  const root = candidates.find(isPackageRoot);
+  if (!root) throw new Error("Unable to locate Lineage package root");
+  return root;
+}
+var repoRoot = resolveRepoRoot();
+var defaultProject = "demo-project";
+var defaultProduct = process.env.LINEAGE_DEFAULT_PRODUCT || defaultProject;
+var publicFallbackBucket = "lineage-demo-assets";
+var publicFallbackRegion = "us-east-1";
+var contentTypes = /* @__PURE__ */ new Set(["image", "video", "gif", "audio", "doc", "other"]);
+var projectNamePattern = /^[a-z0-9][a-z0-9-]*$/;
+var LineageAssetError = class extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+function cleanProject(project = defaultProject) {
+  if (!projectNamePattern.test(project)) {
+    throw new LineageAssetError("Project must be lowercase kebab-case");
+  }
+  return project;
+}
+function catalogPath(project = defaultProject) {
+  return join3(repoRoot, cleanProject(project), "assets", "catalog.json");
+}
+function fixtureCatalogPath(project = defaultProject) {
+  return join3(repoRoot, "fixtures", cleanProject(project), "assets", "catalog.json");
+}
+function normalizeCatalog(catalog, fallbackProject = defaultProject) {
+  const project = cleanProject(catalog.project || catalog.product || fallbackProject);
+  const product = catalog.product || project;
+  return {
+    ...catalog,
+    project,
+    product,
+    default_bucket: catalog.default_bucket || "",
+    default_region: catalog.default_region || "",
+    assets: (catalog.assets || []).map((asset) => ({
+      ...asset,
+      source: asset.source || "catalog",
+      project: asset.project || asset.product || project,
+      product: asset.product || asset.project || project
+    }))
+  };
+}
+function fallbackS3(assetId, channel, status = "working") {
+  return {
+    bucket: publicFallbackBucket,
+    checksum_sha256: void 0,
+    content_type: "image/png",
+    key: `products/${defaultProject}/campaigns/2026-06-public-demo/channels/${channel}/audiences/creators/statuses/${status}/types/image/assets/${assetId}/${assetId}.png`,
+    region: publicFallbackRegion,
+    size_bytes: 2048,
+    updated_at: "2026-06-24T12:00:00.000Z",
+    version_id: "public-demo-version"
+  };
+}
+function fallbackAsset(fields) {
+  return {
+    audience: fields.audience || "creators",
+    campaign: fields.campaign || "2026-06-public-demo",
+    content_type: "image",
+    cta: fields.cta || "Save the idea",
+    hook: fields.hook || "Public demo creative for local review.",
+    product: defaultProject,
+    project: defaultProject,
+    source: "catalog",
+    utm_content: fields.utm_content || fields.asset_id.replace(/-/g, "_"),
+    ...fields
+  };
+}
+function defaultFallbackCatalog() {
+  return normalizeCatalog({
+    assets: [
+      fallbackAsset({
+        asset_id: "demo-meta-short-form-upload-demo-post-static",
+        channel: "meta",
+        s3: fallbackS3("demo-meta-short-form-upload-demo-post-static", "meta"),
+        status: "working",
+        title: "Meta short-form demo post static"
+      }),
+      fallbackAsset({
+        asset_id: "demo-linkedin-ledger-catalog-shared",
+        channel: "linkedin",
+        hook: "Shared ledger creative with catalog metadata.",
+        s3: fallbackS3("demo-linkedin-ledger-catalog-shared", "linkedin"),
+        status: "working",
+        title: "LinkedIn ledger catalog shared"
+      }),
+      fallbackAsset({
+        asset_id: "demo-linkedin-upload-demo-done-static-grounded-v2",
+        channel: "linkedin",
+        placements: [{
+          channel: "linkedin",
+          notes: "Synthetic public scheduled placement.",
+          scheduled_at: "2026-06-24T16:00:00-07:00",
+          status: "scheduled",
+          updated_at: "2026-06-24T12:30:00.000Z"
+        }],
+        s3: fallbackS3("demo-linkedin-upload-demo-done-static-grounded-v2", "linkedin", "approved"),
+        status: "approved",
+        title: "LinkedIn upload demo scheduled static"
+      }),
+      fallbackAsset({
+        asset_id: "demo-tiktok-upload-demo-export-vertical",
+        channel: "tiktok",
+        format: "vertical",
+        hook: "Fast vertical demo export for content queue tests.",
+        s3: fallbackS3("demo-tiktok-upload-demo-export-vertical", "tiktok"),
+        status: "working",
+        title: "TikTok upload demo export vertical"
+      }),
+      fallbackAsset({
+        asset_id: "demo-youtube-short-demo-posted-cut",
+        channel: "youtube",
+        placements: [{
+          channel: "youtube",
+          notes: "Synthetic public posted placement.",
+          posted_at: "2026-06-25T16:00:00-07:00",
+          status: "posted",
+          updated_at: "2026-06-25T17:00:00.000Z"
+        }],
+        s3: fallbackS3("demo-youtube-short-demo-posted-cut", "youtube", "published"),
+        status: "published",
+        title: "YouTube short demo posted cut"
+      }),
+      fallbackAsset({
+        asset_id: "demo-x-twitter-carousel-demo-working-static",
+        channel: "x-twitter",
+        format: "static",
+        s3: fallbackS3("demo-x-twitter-carousel-demo-working-static", "x-twitter"),
+        status: "working",
+        title: "X Twitter carousel demo working static"
+      })
+    ],
+    default_bucket: "",
+    default_region: "",
+    product: defaultProject,
+    project: defaultProject
+  }, defaultProject);
+}
+function loadCatalog(project = defaultProject) {
+  const path = catalogPath(project);
+  if (existsSync3(path)) {
+    try {
+      return normalizeCatalog(JSON.parse(readFileSync2(path, "utf8")), project);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        throw new LineageAssetError(`Missing catalog: ${path}`, 404);
+      }
+      throw error;
+    }
+  }
+  const clean = cleanProject(project);
+  if (clean === defaultProject) {
+    const fixturePath = fixtureCatalogPath(clean);
+    if (existsSync3(fixturePath)) {
+      return normalizeCatalog(JSON.parse(readFileSync2(fixturePath, "utf8")), project);
+    }
+    return defaultFallbackCatalog();
+  }
+  throw new LineageAssetError(`Missing catalog: ${path}`, 404);
+}
+function saveCatalog(project, catalog) {
+  const normalized = normalizeCatalog(catalog, project);
+  mkdirSync2(dirname2(catalogPath(project)), { recursive: true });
+  writeFileSync(catalogPath(project), `${JSON.stringify(normalized, null, 2)}
+`);
+  return normalized;
+}
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      AWS_REGION: process.env.AWS_REGION || "us-east-1",
+      AWS_DEFAULT_REGION: process.env.AWS_DEFAULT_REGION || "us-east-1"
+    }
+  });
+  if (result.status !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new LineageAssetError(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`, 502);
+  }
+  return { stdout: result.stdout, stderr: result.stderr };
+}
+function runAws(args) {
+  return run("aws", args);
+}
+function assetById(catalog, assetId) {
+  const asset = catalog.assets.find((item) => item.asset_id === assetId);
+  if (!asset) throw new LineageAssetError(`Unknown asset: ${assetId}`, 404);
+  return asset;
+}
+var storageAdapter = createS3StorageAdapter({
+  assetById,
+  cleanProject,
+  createError: (message, status) => new LineageAssetError(message, status),
+  defaultProject,
+  loadCatalog,
+  runAws,
+  repoRoot,
+  saveCatalog,
+  supportedContentTypes: contentTypes
+});
+
 // src/server/assetLineageDb.ts
-import { createRequire } from "node:module";
-import { mkdirSync as mkdirSync2 } from "node:fs";
-import { join as join3 } from "node:path";
 var require2 = createRequire(import.meta.url);
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function lineageDbPath() {
-  return process.env.LINEAGE_DB || join3(repoRoot, ".lineage", "asset-lineage.sqlite");
+  return process.env.LINEAGE_DB || join4(repoRoot, ".lineage", "asset-lineage.sqlite");
 }
 function lineageDb() {
-  mkdirSync2(join3(lineageDbPath(), ".."), { recursive: true });
+  mkdirSync3(join4(lineageDbPath(), ".."), { recursive: true });
   const { DatabaseSync } = require2("node:sqlite");
   const database = new DatabaseSync(lineageDbPath());
   database.exec("PRAGMA foreign_keys = ON");
@@ -504,6 +737,41 @@ function lineageDb() {
     );
     create index if not exists generation_job_receipts_job on generation_job_receipts(job_id, created_at);
     create table if not exists adapter_settings (project_id text not null references projects(id), adapter_type text not null check (adapter_type in ('cloud', 'scheduler', 'image_generator')), provider text not null, enabled integer not null check (enabled in (0, 1)), secret_ref text, safe_config_json text not null, created_at text not null, updated_at text not null, primary key(project_id, adapter_type, provider)); create index if not exists adapter_settings_project_type on adapter_settings(project_id, adapter_type);
+    create table if not exists agent_claims (
+      id text primary key,
+      token_hash text not null,
+      project_id text not null references projects(id),
+      channel text,
+      scope_type text not null check (scope_type in ('lineage_workspace', 'content_post', 'content_queue_lane', 'selection_set', 'project_channel')),
+      target_id text not null,
+      target_title text,
+      agent_id text,
+      agent_name text not null,
+      agent_kind text not null,
+      thread_id text,
+      status text not null check (status in ('active', 'expired', 'released', 'revoked', 'transferred')),
+      created_at text not null,
+      heartbeat_at text not null,
+      expires_at text not null,
+      released_at text,
+      revoked_at text,
+      revoked_by text,
+      override_reason text,
+      metadata_json text
+    );
+    create unique index if not exists agent_claims_token_hash on agent_claims(token_hash);
+    create index if not exists agent_claims_project_status on agent_claims(project_id, status, heartbeat_at);
+    create index if not exists agent_claims_target on agent_claims(project_id, channel, scope_type, target_id, status);
+    create table if not exists agent_claim_events (
+      id text primary key,
+      claim_id text not null references agent_claims(id) on delete cascade,
+      event_type text not null,
+      actor text,
+      message text,
+      created_at text not null,
+      metadata_json text
+    );
+    create index if not exists agent_claim_events_claim_created on agent_claim_events(claim_id, created_at);
   `);
   migrateAssetSelections(database);
   dropLegacyAssetSelectionRootUnique(database);
@@ -579,233 +847,362 @@ function ensureReviewStateValues(database) {
   `);
 }
 
-// src/server/assetCore.ts
-function isPackageRoot(path) {
-  const packageJson = join4(path, "package.json");
-  if (!existsSync3(packageJson)) return false;
-  try {
-    const packageInfo = JSON.parse(readFileSync2(packageJson, "utf8"));
-    return packageInfo.name === "@mean-weasel/lineage";
-  } catch {
-    return false;
-  }
-}
-function resolveRepoRoot() {
-  const moduleDir = dirname2(fileURLToPath(import.meta.url));
-  const candidates = [
-    process.env.LINEAGE_REPO_ROOT,
-    resolve2(moduleDir, ".."),
-    resolve2(moduleDir, "../.."),
-    process.cwd()
-  ].filter((candidate) => Boolean(candidate));
-  const root = candidates.find(isPackageRoot);
-  if (!root) throw new Error("Unable to locate Lineage package root");
-  return root;
-}
-var repoRoot = resolveRepoRoot();
-var defaultProject = "demo-project";
-var defaultProduct = process.env.LINEAGE_DEFAULT_PRODUCT || defaultProject;
-var publicFallbackBucket = "lineage-demo-assets";
-var publicFallbackRegion = "us-east-1";
-var contentTypes = /* @__PURE__ */ new Set(["image", "video", "gif", "audio", "doc", "other"]);
-var projectNamePattern = /^[a-z0-9][a-z0-9-]*$/;
-var LineageAssetError = class extends Error {
-  constructor(message, status = 400) {
+// src/server/agentClaims.ts
+var defaultTtlSeconds = 20 * 60;
+var idleAfterSeconds = 5 * 60;
+var staleAfterSeconds = 15 * 60;
+var scopes = /* @__PURE__ */ new Set(["lineage_workspace", "content_post", "content_queue_lane", "selection_set", "project_channel"]);
+var claimTokenPattern = /claim_[a-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+var AgentClaimError = class extends Error {
+  constructor(message, status = 400, code = "agent_claim_error", conflicts = []) {
     super(message);
     this.status = status;
+    this.code = code;
+    this.conflicts = conflicts;
   }
   status;
+  code;
+  conflicts;
 };
-function cleanProject(project = defaultProject) {
-  if (!projectNamePattern.test(project)) {
-    throw new LineageAssetError("Project must be lowercase kebab-case");
+function isAgentClaimError(error) {
+  return error instanceof AgentClaimError;
+}
+function redactAgentClaimTokens(input) {
+  return input.replace(claimTokenPattern, "[redacted-claim-token]");
+}
+function parseClaimTtl(value) {
+  if (!value) return defaultTtlSeconds;
+  const match = value.trim().match(/^(\d+)(s|m|h)?$/);
+  if (!match) throw new AgentClaimError(`Invalid claim ttl: ${value}`);
+  const amount = Number(match[1]);
+  const unit = match[2] || "s";
+  const multiplier = unit === "h" ? 3600 : unit === "m" ? 60 : 1;
+  const seconds = amount * multiplier;
+  if (!Number.isInteger(seconds) || seconds < 30 || seconds > 24 * 60 * 60) {
+    throw new AgentClaimError("Claim ttl must be between 30 seconds and 24 hours");
   }
-  return project;
+  return seconds;
 }
-function catalogPath(project = defaultProject) {
-  return join4(repoRoot, cleanProject(project), "assets", "catalog.json");
+function randomId(prefix) {
+  return `${prefix}_${Date.now().toString(36)}_${randomBytes(6).toString("base64url").toLowerCase()}`;
 }
-function fixtureCatalogPath(project = defaultProject) {
-  return join4(repoRoot, "fixtures", cleanProject(project), "assets", "catalog.json");
+function tokenHash(token) {
+  return createHash2("sha256").update(token).digest("hex");
 }
-function normalizeCatalog(catalog, fallbackProject = defaultProject) {
-  const project = cleanProject(catalog.project || catalog.product || fallbackProject);
-  const product = catalog.product || project;
-  return {
-    ...catalog,
-    project,
-    product,
-    default_bucket: catalog.default_bucket || "",
-    default_region: catalog.default_region || "",
-    assets: (catalog.assets || []).map((asset) => ({
-      ...asset,
-      source: asset.source || "catalog",
-      project: asset.project || asset.product || project,
-      product: asset.product || asset.project || project
-    }))
-  };
+function safeEqual(a, b) {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
 }
-function fallbackS3(assetId, channel, status = "working") {
+function expiresAtFrom(timestamp, ttlSeconds) {
+  return new Date(new Date(timestamp).getTime() + ttlSeconds * 1e3).toISOString();
+}
+function metadataJson(metadata) {
+  return metadata ? JSON.stringify(metadata) : null;
+}
+function parseMetadata(value) {
+  if (typeof value !== "string" || !value) return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function derivedState(row, now = /* @__PURE__ */ new Date()) {
+  if (row.status !== "active") return row.status === "expired" ? "expired" : "stale";
+  if (new Date(row.expires_at).getTime() <= now.getTime()) return "expired";
+  const ageSeconds = Math.max(0, Math.floor((now.getTime() - new Date(row.heartbeat_at).getTime()) / 1e3));
+  if (ageSeconds >= staleAfterSeconds) return "stale";
+  if (ageSeconds >= idleAfterSeconds) return "idle";
+  return "active";
+}
+function rowToClaim(row, now = /* @__PURE__ */ new Date()) {
+  const heartbeatAt = String(row.heartbeat_at);
   return {
-    bucket: publicFallbackBucket,
-    checksum_sha256: void 0,
-    content_type: "image/png",
-    key: `products/${defaultProject}/campaigns/2026-06-public-demo/channels/${channel}/audiences/creators/statuses/${status}/types/image/assets/${assetId}/${assetId}.png`,
-    region: publicFallbackRegion,
-    size_bytes: 2048,
-    updated_at: "2026-06-24T12:00:00.000Z",
-    version_id: "public-demo-version"
+    id: String(row.id),
+    project: String(row.project_id),
+    channel: typeof row.channel === "string" ? row.channel : void 0,
+    scope_type: String(row.scope_type),
+    target_id: String(row.target_id),
+    target_title: typeof row.target_title === "string" ? row.target_title : void 0,
+    agent_id: typeof row.agent_id === "string" ? row.agent_id : void 0,
+    agent_name: String(row.agent_name),
+    agent_kind: String(row.agent_kind),
+    thread_id: typeof row.thread_id === "string" ? row.thread_id : void 0,
+    status: String(row.status),
+    created_at: String(row.created_at),
+    heartbeat_at: heartbeatAt,
+    expires_at: String(row.expires_at),
+    released_at: typeof row.released_at === "string" ? row.released_at : void 0,
+    revoked_at: typeof row.revoked_at === "string" ? row.revoked_at : void 0,
+    revoked_by: typeof row.revoked_by === "string" ? row.revoked_by : void 0,
+    override_reason: typeof row.override_reason === "string" ? row.override_reason : void 0,
+    metadata: parseMetadata(row.metadata_json),
+    heartbeat_age_seconds: Math.max(0, Math.floor((now.getTime() - new Date(heartbeatAt).getTime()) / 1e3)),
+    derived_state: derivedState({
+      expires_at: String(row.expires_at),
+      heartbeat_at: heartbeatAt,
+      status: String(row.status)
+    }, now)
   };
 }
-function fallbackAsset(fields) {
+function eventToRow(row) {
   return {
-    audience: fields.audience || "creators",
-    campaign: fields.campaign || "2026-06-public-demo",
-    content_type: "image",
-    cta: fields.cta || "Save the idea",
-    hook: fields.hook || "Public demo creative for local review.",
-    product: defaultProject,
-    project: defaultProject,
-    source: "catalog",
-    utm_content: fields.utm_content || fields.asset_id.replace(/-/g, "_"),
-    ...fields
+    claim_id: String(row.claim_id),
+    event_type: String(row.event_type),
+    actor: typeof row.actor === "string" ? row.actor : void 0,
+    message: typeof row.message === "string" ? row.message : void 0,
+    created_at: String(row.created_at),
+    metadata: parseMetadata(row.metadata_json)
   };
 }
-function defaultFallbackCatalog() {
-  return normalizeCatalog({
-    assets: [
-      fallbackAsset({
-        asset_id: "demo-meta-short-form-upload-demo-post-static",
-        channel: "meta",
-        s3: fallbackS3("demo-meta-short-form-upload-demo-post-static", "meta"),
-        status: "working",
-        title: "Meta short-form demo post static"
-      }),
-      fallbackAsset({
-        asset_id: "demo-linkedin-ledger-catalog-shared",
-        channel: "linkedin",
-        hook: "Shared ledger creative with catalog metadata.",
-        s3: fallbackS3("demo-linkedin-ledger-catalog-shared", "linkedin"),
-        status: "working",
-        title: "LinkedIn ledger catalog shared"
-      }),
-      fallbackAsset({
-        asset_id: "demo-linkedin-upload-demo-done-static-grounded-v2",
-        channel: "linkedin",
-        placements: [{
-          channel: "linkedin",
-          notes: "Synthetic public scheduled placement.",
-          scheduled_at: "2026-06-24T16:00:00-07:00",
-          status: "scheduled",
-          updated_at: "2026-06-24T12:30:00.000Z"
-        }],
-        s3: fallbackS3("demo-linkedin-upload-demo-done-static-grounded-v2", "linkedin", "approved"),
-        status: "approved",
-        title: "LinkedIn upload demo scheduled static"
-      }),
-      fallbackAsset({
-        asset_id: "demo-tiktok-upload-demo-export-vertical",
-        channel: "tiktok",
-        format: "vertical",
-        hook: "Fast vertical demo export for content queue tests.",
-        s3: fallbackS3("demo-tiktok-upload-demo-export-vertical", "tiktok"),
-        status: "working",
-        title: "TikTok upload demo export vertical"
-      }),
-      fallbackAsset({
-        asset_id: "demo-youtube-short-demo-posted-cut",
-        channel: "youtube",
-        placements: [{
-          channel: "youtube",
-          notes: "Synthetic public posted placement.",
-          posted_at: "2026-06-25T16:00:00-07:00",
-          status: "posted",
-          updated_at: "2026-06-25T17:00:00.000Z"
-        }],
-        s3: fallbackS3("demo-youtube-short-demo-posted-cut", "youtube", "published"),
-        status: "published",
-        title: "YouTube short demo posted cut"
-      }),
-      fallbackAsset({
-        asset_id: "demo-x-twitter-carousel-demo-working-static",
-        channel: "x-twitter",
-        format: "static",
-        s3: fallbackS3("demo-x-twitter-carousel-demo-working-static", "x-twitter"),
-        status: "working",
-        title: "X Twitter carousel demo working static"
-      })
-    ],
-    default_bucket: "",
-    default_region: "",
-    product: defaultProject,
-    project: defaultProject
-  }, defaultProject);
+function ensureProject(database, project) {
+  const timestamp = nowIso();
+  database.prepare(`
+    insert into projects (id, product, created_at, updated_at)
+    values (?, ?, ?, ?)
+    on conflict(id) do update set product = excluded.product, updated_at = excluded.updated_at
+  `).run(project, project, timestamp, timestamp);
+}
+function recordEvent(database, claimId, eventType, actor, message, metadata) {
+  database.prepare(`
+    insert into agent_claim_events (id, claim_id, event_type, actor, message, created_at, metadata_json)
+    values (?, ?, ?, ?, ?, ?, ?)
+  `).run(randomId("claim_event"), claimId, eventType, actor || null, message || null, nowIso(), metadataJson(metadata));
 }
-function loadCatalog(project = defaultProject) {
-  const path = catalogPath(project);
-  if (existsSync3(path)) {
-    try {
-      return normalizeCatalog(JSON.parse(readFileSync2(path, "utf8")), project);
-    } catch (error) {
-      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-        throw new LineageAssetError(`Missing catalog: ${path}`, 404);
-      }
-      throw error;
+function expireActiveClaims(database) {
+  const timestamp = nowIso();
+  const expired = database.prepare(`
+    select id from agent_claims where status = 'active' and expires_at <= ?
+  `).all(timestamp);
+  if (expired.length === 0) return;
+  database.prepare(`
+    update agent_claims set status = 'expired' where status = 'active' and expires_at <= ?
+  `).run(timestamp);
+  for (const claim of expired) recordEvent(database, claim.id, "expired", "system", "Claim expired after missed heartbeat.");
+}
+function normalizeScope(scopeType) {
+  if (!scopes.has(scopeType)) throw new AgentClaimError(`Unsupported claim scope: ${scopeType}`);
+  return scopeType;
+}
+function channelOverlaps(left, right) {
+  return !left || !right || left === right;
+}
+function claimOverlaps(candidate, existing) {
+  if (candidate.project !== existing.project) return false;
+  if (!channelOverlaps(candidate.channel, existing.channel)) return false;
+  if (candidate.scope_type === existing.scope_type && candidate.target_id === existing.target_id) return true;
+  return candidate.scope_type === "project_channel" || existing.scope_type === "project_channel";
+}
+function activeClaims(database, project) {
+  const rows = project ? database.prepare("select * from agent_claims where project_id = ? and status = 'active' order by heartbeat_at desc").all(project) : database.prepare("select * from agent_claims where status = 'active' order by project_id, heartbeat_at desc").all();
+  return rows.map((row) => rowToClaim(row));
+}
+function findClaimById(database, claimId, project) {
+  const row = project ? database.prepare("select * from agent_claims where project_id = ? and id = ?").get(project, claimId) : database.prepare("select * from agent_claims where id = ?").get(claimId);
+  return row ? rowToClaim(row) : null;
+}
+function findClaimRowByToken(database, claimToken) {
+  const claimId = claimToken.split(".")[0];
+  const row = database.prepare("select * from agent_claims where id = ?").get(claimId);
+  if (!row) return null;
+  return safeEqual(String(row.token_hash), tokenHash(claimToken)) ? row : null;
+}
+function denied(code, message, conflicts = []) {
+  return { ok: false, code, message, conflicts };
+}
+function scopeAllowsWrite(claim, scopeType, targetId, writeKind) {
+  if (claim.scope_type === scopeType && claim.target_id === targetId) return true;
+  if (claim.scope_type === "project_channel") return true;
+  if (claim.scope_type === "lineage_workspace" && scopeType === "lineage_workspace") return claim.target_id === targetId;
+  if (claim.scope_type === "content_queue_lane" && writeKind === "content_queue_next") return true;
+  return false;
+}
+function createAgentClaim(fields) {
+  const project = fields.project.trim();
+  const targetId = fields.targetId.trim();
+  const agentName = fields.agentName.trim();
+  if (!project) throw new AgentClaimError("Agent claim requires project");
+  if (!targetId) throw new AgentClaimError("Agent claim requires target");
+  if (!agentName) throw new AgentClaimError("Agent claim requires agent name");
+  const scopeType = normalizeScope(fields.scopeType);
+  const ttlSeconds = fields.ttlSeconds || defaultTtlSeconds;
+  const database = lineageDb();
+  try {
+    ensureProject(database, project);
+    expireActiveClaims(database);
+    const candidate = { project, channel: fields.channel?.trim() || void 0, scope_type: scopeType, target_id: targetId };
+    const conflicts = activeClaims(database, project).filter((claim2) => claimOverlaps(candidate, claim2));
+    if (conflicts.length > 0 && !fields.force) {
+      throw new AgentClaimError("Target already has an active overlapping agent claim.", 409, "target_already_claimed", conflicts);
     }
-  }
-  const clean = cleanProject(project);
-  if (clean === defaultProject) {
-    const fixturePath = fixtureCatalogPath(clean);
-    if (existsSync3(fixturePath)) {
-      return normalizeCatalog(JSON.parse(readFileSync2(fixturePath, "utf8")), project);
+    if (conflicts.length > 0 && !fields.reason?.trim()) {
+      throw new AgentClaimError("Overriding an active claim requires --reason.", 400, "override_reason_required", conflicts);
     }
-    return defaultFallbackCatalog();
+    const timestamp = nowIso();
+    for (const conflict of conflicts) {
+      database.prepare(`
+        update agent_claims
+        set status = 'revoked', revoked_at = ?, revoked_by = ?, override_reason = ?
+        where id = ? and status = 'active'
+      `).run(timestamp, agentName, fields.reason || null, conflict.id);
+      recordEvent(database, conflict.id, "revoked", agentName, fields.reason || "Revoked by forced claim takeover.");
+      recordEvent(database, conflict.id, "conflict", agentName, `Overridden by ${agentName}.`, { new_claim_target: targetId });
+    }
+    const id = randomId("claim");
+    const secret = randomBytes(24).toString("base64url");
+    const claimToken = `${id}.${secret}`;
+    const expiresAt = expiresAtFrom(timestamp, ttlSeconds);
+    database.prepare(`
+      insert into agent_claims (
+        id, token_hash, project_id, channel, scope_type, target_id, target_title, agent_id, agent_name,
+        agent_kind, thread_id, status, created_at, heartbeat_at, expires_at, metadata_json
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)
+    `).run(
+      id,
+      tokenHash(claimToken),
+      project,
+      candidate.channel || null,
+      scopeType,
+      targetId,
+      fields.targetTitle?.trim() || null,
+      fields.agentId?.trim() || null,
+      agentName,
+      fields.agentKind?.trim() || "codex",
+      fields.threadId?.trim() || null,
+      timestamp,
+      timestamp,
+      expiresAt,
+      metadataJson(fields.metadata)
+    );
+    recordEvent(database, id, "created", agentName, `Claimed ${scopeType} ${targetId}.`, { ttl_seconds: ttlSeconds });
+    const claim = findClaimById(database, id);
+    return { ok: true, claim, claim_token: claimToken, conflicts_revoked: conflicts.map((conflict) => conflict.id) };
+  } finally {
+    database.close();
   }
-  throw new LineageAssetError(`Missing catalog: ${path}`, 404);
 }
-function saveCatalog(project, catalog) {
-  const normalized = normalizeCatalog(catalog, project);
-  mkdirSync3(dirname2(catalogPath(project)), { recursive: true });
-  writeFileSync(catalogPath(project), `${JSON.stringify(normalized, null, 2)}
-`);
-  return normalized;
+function listAgentClaims(project) {
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const rows = project ? database.prepare("select * from agent_claims where project_id = ? order by status, heartbeat_at desc").all(project) : database.prepare("select * from agent_claims order by project_id, status, heartbeat_at desc").all();
+    return { ok: true, claims: rows.map((row) => rowToClaim(row)), fetchedAt: nowIso() };
+  } finally {
+    database.close();
+  }
 }
-function run(command, args) {
-  const result = spawnSync(command, args, {
-    cwd: repoRoot,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    env: {
-      ...process.env,
-      AWS_REGION: process.env.AWS_REGION || "us-east-1",
-      AWS_DEFAULT_REGION: process.env.AWS_DEFAULT_REGION || "us-east-1"
-    }
-  });
-  if (result.status !== 0) {
-    const detail = result.stderr.trim() || result.stdout.trim();
-    throw new LineageAssetError(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`, 502);
+function inspectAgentClaim(claimId, project) {
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const claim = findClaimById(database, claimId, project);
+    if (!claim) throw new AgentClaimError(`Unknown agent claim: ${claimId}`, 404, "claim_not_found");
+    const events = database.prepare("select * from agent_claim_events where claim_id = ? order by created_at").all(claim.id);
+    return { ok: true, claim, events: events.map(eventToRow) };
+  } finally {
+    database.close();
   }
-  return { stdout: result.stdout, stderr: result.stderr };
 }
-function runAws(args) {
-  return run("aws", args);
+function heartbeatAgentClaim(claimToken, ttlSeconds = defaultTtlSeconds) {
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const row = findClaimRowByToken(database, claimToken);
+    if (!row) throw new AgentClaimError("Unknown or invalid agent claim token.", 401, "claim_token_invalid");
+    const claim = rowToClaim(row);
+    if (claim.status !== "active") throw new AgentClaimError(`Agent claim is ${claim.status}.`, 409, "claim_not_active");
+    const timestamp = nowIso();
+    database.prepare("update agent_claims set heartbeat_at = ?, expires_at = ? where id = ?").run(timestamp, expiresAtFrom(timestamp, ttlSeconds), claim.id);
+    recordEvent(database, claim.id, "heartbeat", claim.agent_name, "Claim heartbeat received.");
+    return { ok: true, claim: findClaimById(database, claim.id) };
+  } finally {
+    database.close();
+  }
 }
-function assetById(catalog, assetId) {
-  const asset = catalog.assets.find((item) => item.asset_id === assetId);
-  if (!asset) throw new LineageAssetError(`Unknown asset: ${assetId}`, 404);
-  return asset;
+function releaseAgentClaim(claimToken) {
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const row = findClaimRowByToken(database, claimToken);
+    if (!row) throw new AgentClaimError("Unknown or invalid agent claim token.", 401, "claim_token_invalid");
+    const claim = rowToClaim(row);
+    if (claim.status !== "active") throw new AgentClaimError(`Agent claim is ${claim.status}.`, 409, "claim_not_active");
+    const timestamp = nowIso();
+    database.prepare("update agent_claims set status = 'released', released_at = ? where id = ?").run(timestamp, claim.id);
+    recordEvent(database, claim.id, "released", claim.agent_name, "Claim released by token holder.");
+    return { ok: true, claim: findClaimById(database, claim.id) };
+  } finally {
+    database.close();
+  }
+}
+function revokeAgentClaim(project, claimId, fields) {
+  if (!fields.confirmWrite) throw new AgentClaimError("Revoking an agent claim requires confirmWrite=true.", 400, "confirm_write_required");
+  if (!fields.reason?.trim()) throw new AgentClaimError("Revoking an agent claim requires a reason.", 400, "reason_required");
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const claim = findClaimById(database, claimId, project);
+    if (!claim) throw new AgentClaimError(`Unknown agent claim: ${claimId}`, 404, "claim_not_found");
+    const timestamp = nowIso();
+    database.prepare(`
+      update agent_claims set status = 'revoked', revoked_at = ?, revoked_by = ?, override_reason = ?
+      where id = ?
+    `).run(timestamp, fields.actor || "human", fields.reason, claim.id);
+    recordEvent(database, claim.id, "revoked", fields.actor || "human", fields.reason);
+    return { ok: true, claim: findClaimById(database, claim.id) };
+  } finally {
+    database.close();
+  }
+}
+function transferAgentClaim(project, claimId, fields) {
+  if (!fields.confirmWrite) throw new AgentClaimError("Transferring an agent claim requires confirmWrite=true.", 400, "confirm_write_required");
+  const toAgentName = fields.toAgentName.trim();
+  if (!toAgentName) throw new AgentClaimError("Transfer requires toAgentName.", 400, "agent_name_required");
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const claim = findClaimById(database, claimId, project);
+    if (!claim) throw new AgentClaimError(`Unknown agent claim: ${claimId}`, 404, "claim_not_found");
+    if (claim.status !== "active") throw new AgentClaimError(`Agent claim is ${claim.status}.`, 409, "claim_not_active");
+    database.prepare("update agent_claims set agent_name = ? where id = ?").run(toAgentName, claim.id);
+    recordEvent(database, claim.id, "transferred", fields.actor || "human", fields.reason || `Transferred claim to ${toAgentName}.`, { to_agent_name: toAgentName });
+    return { ok: true, claim: findClaimById(database, claim.id) };
+  } finally {
+    database.close();
+  }
+}
+function validateAgentClaimForWrite(fields) {
+  if (fields.dangerLevel === "danger" && !fields.confirmWrite) {
+    return denied("human_confirmation_required", "Dangerous write requires explicit human confirmation.");
+  }
+  if (!fields.claimToken) return denied("claim_required", "Mutating agent write requires a matching claim token.");
+  const database = lineageDb();
+  try {
+    expireActiveClaims(database);
+    const row = findClaimRowByToken(database, fields.claimToken);
+    if (!row) return denied("claim_token_invalid", "Unknown or invalid claim token.");
+    const claim = rowToClaim(row);
+    if (claim.status !== "active") return denied("claim_not_active", `Agent claim is ${claim.status}.`);
+    if (new Date(claim.expires_at).getTime() <= Date.now()) return denied("claim_expired", "Agent claim has expired.");
+    if (claim.project !== fields.project) return denied("claim_project_mismatch", `Claim project ${claim.project} does not match ${fields.project}.`, [claim]);
+    if (fields.channel && claim.channel && claim.channel !== fields.channel) {
+      return denied("claim_channel_mismatch", `Claim channel ${claim.channel} does not match ${fields.channel}.`, [claim]);
+    }
+    if (!scopeAllowsWrite(claim, fields.scopeType, fields.targetId, fields.writeKind)) {
+      return denied("claim_scope_mismatch", `Claim does not cover ${fields.scopeType} ${fields.targetId}.`, [claim]);
+    }
+    recordEvent(database, claim.id, "write_allowed", claim.agent_name, `${fields.writeKind} allowed.`, {
+      danger_level: fields.dangerLevel,
+      target_id: fields.targetId,
+      write_kind: fields.writeKind
+    });
+    return { ok: true, claim, warnings: [] };
+  } finally {
+    database.close();
+  }
 }
-var storageAdapter = createS3StorageAdapter({
-  assetById,
-  cleanProject,
-  createError: (message, status) => new LineageAssetError(message, status),
-  defaultProject,
-  loadCatalog,
-  runAws,
-  repoRoot,
-  saveCatalog,
-  supportedContentTypes: contentTypes
-});
 
 // src/server/assetLineageSelection.ts
 function selectedRows(database, project, root) {
@@ -821,7 +1218,7 @@ function selectedRows(database, project, root) {
 function lineageWorkspaceId(project, rootAssetId) {
   return `${project}:lineage-workspace:${rootAssetId}`;
 }
-function ensureProject(database, project) {
+function ensureProject2(database, project) {
   const timestamp = nowIso();
   database.prepare(`
     insert into projects (id, product, created_at, updated_at)
@@ -858,7 +1255,7 @@ function knownRoots(database, project) {
   return rows.map((row) => ({ root_asset_id: row.root_asset_id, selected_at: row.selected_at || void 0 }));
 }
 function seedLegacyWorkspaces(database, project) {
-  ensureProject(database, project);
+  ensureProject2(database, project);
   const timestamp = nowIso();
   const statement = database.prepare(`
     insert into lineage_workspaces (
@@ -900,6 +1297,37 @@ function activeLineageWorkspaceRoot(project) {
   }
 }
 
+// src/server/lineageClaimGuards.ts
+function channelOverlaps2(left, right) {
+  return !left || !right || left === right;
+}
+function hasActiveLineageWorkspaceClaim(project, targetId, channel) {
+  return listAgentClaims(project).claims.some((claim) => {
+    if (claim.project !== project || claim.status !== "active" || claim.derived_state === "expired") return false;
+    if (claim.scope_type === "lineage_workspace") return claim.target_id === targetId;
+    return claim.scope_type === "project_channel" && channelOverlaps2(channel, claim.channel);
+  });
+}
+function requireLineageWorkspaceClaimForWrite(fields) {
+  if (!fields.confirmWrite) return;
+  const targetId = lineageWorkspaceId(fields.project, fields.rootAssetId);
+  if (!fields.claimToken && !hasActiveLineageWorkspaceClaim(fields.project, targetId, fields.channel)) return;
+  const validation = validateAgentClaimForWrite({
+    channel: fields.channel,
+    claimToken: fields.claimToken,
+    confirmWrite: fields.confirmWrite,
+    dangerLevel: "enforce",
+    project: fields.project,
+    scopeType: "lineage_workspace",
+    targetId,
+    writeKind: fields.writeKind
+  });
+  if (!validation.ok) {
+    const status = validation.code === "claim_required" || validation.code === "claim_token_invalid" ? 401 : 409;
+    throw new AgentClaimError(validation.message, status, validation.code, validation.conflicts);
+  }
+}
+
 // src/server/assetLineage.ts
 var LineageError = class extends Error {
   constructor(message, status = 400) {
@@ -927,6 +1355,45 @@ function rootFor(database, project, assetId) {
   }
   return assetId;
 }
+function explicitWorkspaceRoot(database, project, assetId) {
+  const row = database.prepare(`
+    select root_asset_id from lineage_workspaces
+    where project_id = ? and root_asset_id = ? and status != 'archived'
+  `).get(project, assetId);
+  return row?.root_asset_id;
+}
+function nearestWorkspaceRoot(database, project, assetId) {
+  let current = assetId;
+  const seen = /* @__PURE__ */ new Set();
+  while (!seen.has(current)) {
+    seen.add(current);
+    const explicit = explicitWorkspaceRoot(database, project, current);
+    if (explicit) return explicit;
+    const parent = parentOf(database, project, current);
+    if (!parent) return current;
+    current = parent;
+  }
+  return assetId;
+}
+function assetChannel(database, project, assetId) {
+  const row = database.prepare("select channel from assets where project_id = ? and id = ?").get(project, assetId);
+  return row?.channel;
+}
+function lineageWriteClaimContext(database, project, assetId) {
+  return {
+    channel: assetChannel(database, project, assetId),
+    rootAssetId: nearestWorkspaceRoot(database, project, assetId)
+  };
+}
+function getLineageWriteClaimContext(project, assetId) {
+  const database = lineageDb();
+  try {
+    requireAsset(database, project, assetId);
+    return lineageWriteClaimContext(database, project, assetId);
+  } finally {
+    database.close();
+  }
+}
 function latestSelectedRoot(database, project) {
   const row = database.prepare("select root_asset_id from asset_selections where project_id = ? order by selected_at desc limit 1").get(project);
   return row?.root_asset_id;
@@ -957,6 +1424,20 @@ function linkLineageAssets(project, fields) {
   requireAsset(database, project, fields.parentAssetId);
   requireAsset(database, project, fields.childAssetId);
   if (fields.parentAssetId === fields.childAssetId) throw new LineageError("Lineage link cannot point to itself");
+  const claimContext = lineageWriteClaimContext(database, project, fields.parentAssetId);
+  try {
+    requireLineageWorkspaceClaimForWrite({
+      channel: claimContext.channel,
+      claimToken: fields.claimToken,
+      confirmWrite: fields.confirmWrite,
+      project,
+      rootAssetId: claimContext.rootAssetId,
+      writeKind: "lineage_link"
+    });
+  } catch (error) {
+    database.close();
+    throw error;
+  }
   const edge = {
     id: edgeId(project, fields.parentAssetId, fields.childAssetId),
     parent_asset_id: fields.parentAssetId,
@@ -993,7 +1474,7 @@ function descendants(database, project, root) {
 function getLineageSnapshot(project, assetId) {
   const database = lineageDb();
   requireAsset(database, project, assetId);
-  const root = rootFor(database, project, assetId);
+  const root = explicitWorkspaceRoot(database, project, assetId) || rootFor(database, project, assetId);
   const edges = descendants(database, project, root);
   const ids = [.../* @__PURE__ */ new Set([root, ...edges.flatMap((edge) => [edge.parent_asset_id, edge.child_asset_id])])];
   const placeholders = ids.map(() => "?").join(",");
@@ -1168,9 +1649,24 @@ function getLineageBrief(project, rootAssetId) {
 function linkSelectedLineageChild(project, fields) {
   const next = getLineageNextAsset(project, fields.rootAssetId);
   if (!next.next_asset) throw new LineageError("Cannot link child until a next base is selected or unambiguous");
+  if (fields.confirmWrite) {
+    const claimContext = getLineageWriteClaimContext(project, next.next_asset.asset_id);
+    const validation = validateAgentClaimForWrite({
+      channel: claimContext.channel,
+      claimToken: fields.claimToken,
+      confirmWrite: fields.confirmWrite,
+      dangerLevel: "enforce",
+      project,
+      scopeType: "lineage_workspace",
+      targetId: lineageWorkspaceId(project, claimContext.rootAssetId),
+      writeKind: "link_child"
+    });
+    if (!validation.ok) throw new AgentClaimError(validation.message, validation.code === "claim_required" ? 401 : 403, validation.code, validation.conflicts);
+  }
   const result = linkLineageAssets(project, {
     childAssetId: fields.childAssetId,
     confirmWrite: fields.confirmWrite,
+    claimToken: fields.claimToken,
     parentAssetId: next.next_asset.asset_id
   });
   return {
@@ -1236,7 +1732,15 @@ Usage:
   ${config.binName} next [--project <project>] [--root <asset-id>] [--db <path>] [--json]
   ${config.binName} brief [--project <project>] [--root <asset-id>] [--db <path>] [--json]
   ${config.binName} inspect --asset-id <asset-id> [--project <project>] [--db <path>] [--json]
-  ${config.binName} link-child --root <asset-id> --child <asset-id> [--project <project>] [--confirm-write] [--db <path>] [--json]
+  ${config.binName} link-child --root <asset-id> --child <asset-id> [--project <project>] [--claim-token <claim-id.secret>] [--confirm-write] [--db <path>] [--json]
+  ${config.binName} agent claim --project <project> --scope <scope> --target <target-id> --agent-name <name> [--channel <channel>] [--ttl 20m] [--json]
+  ${config.binName} agent graph --root <asset-id> [--project <project>] [--db <path>] [--json]
+  ${config.binName} agent status [--project <project>] [--json]
+  ${config.binName} agent inspect --claim <claim-id> [--project <project>] [--json]
+  ${config.binName} agent heartbeat --claim-token <claim-id.secret> [--json]
+  ${config.binName} agent release --claim-token <claim-id.secret> [--json]
+  ${config.binName} agent revoke --claim <claim-id> --project <project> --reason <text> --confirm-write [--json]
+  ${config.binName} agent transfer --claim <claim-id> --to-agent-name <name> --confirm-write [--project <project>] [--json]
   ${config.binName} --help
   ${config.binName} --version
 
@@ -1265,6 +1769,7 @@ function resolveDataCommandOptions(args) {
   const options = {
     assetId: readOption(args, "--asset-id") || positions[0],
     childAssetId: readOption(args, "--child"),
+    claimToken: readOption(args, "--claim-token") || process.env.LINEAGE_CLAIM_TOKEN,
     confirmWrite: args.includes("--confirm-write"),
     dbPath: readOption(args, "--db"),
     json: args.includes("--json"),
@@ -1286,6 +1791,7 @@ function runLineageDataCommand(command, args) {
     if (!options.childAssetId) throw new Error("lineage link-child requires --child");
     return linkSelectedLineageChild(options.project, {
       childAssetId: options.childAssetId,
+      claimToken: options.claimToken,
       confirmWrite: options.confirmWrite,
       rootAssetId: options.rootAssetId || options.assetId
     });
@@ -1322,6 +1828,121 @@ function printDataResult(command, result, json) {
   }
   console.log(String(result));
 }
+function runLineageAgentCommand(command, args) {
+  const dbPath = readOption(args, "--db");
+  if (dbPath) process.env.LINEAGE_DB = dbPath;
+  const project = readOption(args, "--project") || process.env.LINEAGE_DEFAULT_PRODUCT || defaultProduct;
+  const claimId = readOption(args, "--claim");
+  const claimToken = readOption(args, "--claim-token") || process.env.LINEAGE_CLAIM_TOKEN;
+  if (command === "claim") {
+    return createAgentClaim({
+      agentId: readOption(args, "--agent-id"),
+      agentKind: readOption(args, "--agent-kind"),
+      agentName: readOption(args, "--agent-name") || "",
+      channel: readOption(args, "--channel"),
+      force: args.includes("--force"),
+      project,
+      reason: readOption(args, "--reason"),
+      scopeType: readOption(args, "--scope") || "",
+      targetId: readOption(args, "--target") || "",
+      targetTitle: readOption(args, "--target-title"),
+      threadId: readOption(args, "--thread-id"),
+      ttlSeconds: parseClaimTtl(readOption(args, "--ttl"))
+    });
+  }
+  if (command === "status") return listAgentClaims(project);
+  if (command === "graph") {
+    const rootAssetId = readOption(args, "--root") || readOption(args, "--asset-id") || positionalArgs(args)[0];
+    if (!rootAssetId) throw new Error("lineage agent graph requires --root");
+    return getLineageSnapshot(project, rootAssetId);
+  }
+  if (command === "inspect") {
+    if (!claimId) throw new Error("lineage agent inspect requires --claim");
+    return inspectAgentClaim(claimId, project);
+  }
+  if (command === "heartbeat") {
+    if (!claimToken) throw new Error("lineage agent heartbeat requires --claim-token");
+    return heartbeatAgentClaim(claimToken, parseClaimTtl(readOption(args, "--ttl")));
+  }
+  if (command === "release") {
+    if (!claimToken) throw new Error("lineage agent release requires --claim-token");
+    return releaseAgentClaim(claimToken);
+  }
+  if (command === "revoke") {
+    if (!claimId) throw new Error("lineage agent revoke requires --claim");
+    return revokeAgentClaim(project, claimId, {
+      actor: readOption(args, "--actor") || "human",
+      confirmWrite: args.includes("--confirm-write"),
+      reason: readOption(args, "--reason")
+    });
+  }
+  if (command === "transfer") {
+    if (!claimId) throw new Error("lineage agent transfer requires --claim");
+    return transferAgentClaim(project, claimId, {
+      actor: readOption(args, "--actor") || "human",
+      confirmWrite: args.includes("--confirm-write"),
+      reason: readOption(args, "--reason"),
+      toAgentName: readOption(args, "--to-agent-name") || ""
+    });
+  }
+  throw new Error(`Unknown agent command: ${command}`);
+}
+function printAgentResult(command, result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (command === "claim" && result && typeof result === "object" && "claim" in result) {
+    const created = result;
+    console.log(`Claimed ${created.claim?.target_id || "target"} as ${created.claim?.id || "claim"}`);
+    if (created.claim_token) console.log(`Token: ${created.claim_token}`);
+    return;
+  }
+  if (command === "status" && result && typeof result === "object" && "claims" in result) {
+    const status = result;
+    if (status.claims.length === 0) {
+      console.log("No agent claims.");
+      return;
+    }
+    for (const claim of status.claims) console.log(`${claim.agent_name} ${claim.derived_state} ${claim.target_id}`);
+    return;
+  }
+  if (result && typeof result === "object" && "claim" in result) {
+    const inspected = result;
+    console.log(`${inspected.claim?.id || "claim"} ${inspected.claim?.status || "unknown"} ${inspected.claim?.target_id || ""}`.trim());
+    return;
+  }
+  if (command === "graph" && result && typeof result === "object" && "nodes" in result) {
+    console.log(formatAgentGraphDigest(result));
+    return;
+  }
+  console.log(String(result));
+}
+function formatAgentGraphDigest(snapshot) {
+  const lines = [];
+  const titleFor = (assetId) => {
+    const node = snapshot.nodes.find((item) => item.asset_id === assetId);
+    return node?.title ? `${node.title} (${assetId})` : assetId;
+  };
+  const root = snapshot.nodes.find((node) => node.asset_id === snapshot.root_asset_id);
+  lines.push(`Lineage graph: ${root?.title || snapshot.root_asset_id}`);
+  lines.push(`Root: ${snapshot.root_asset_id}`);
+  lines.push(`Active: ${titleFor(snapshot.active_asset_id)}`);
+  lines.push(`Nodes: ${snapshot.nodes.length}  Edges: ${snapshot.edges.length}`);
+  const selected = snapshot.selected || [];
+  if (selected.length > 0) {
+    lines.push("Next variation:");
+    for (const assetId of selected) lines.push(`- ${titleFor(assetId)}`);
+  }
+  const latest = snapshot.latest || snapshot.nodes.filter((node) => node.is_latest).map((node) => node.asset_id);
+  if (latest.length > 0) {
+    lines.push("Latest leaves:");
+    for (const assetId of latest) lines.push(`- ${titleFor(assetId)}`);
+  }
+  lines.push("Edges:");
+  for (const edge of snapshot.edges) lines.push(`- ${titleFor(edge.parent_asset_id)} -> ${titleFor(edge.child_asset_id)}`);
+  return lines.join("\n");
+}
 function start(config, args) {
   let options;
   const json = args.includes("--json");
@@ -1394,9 +2015,29 @@ function runLineageCli(config, args = process.argv.slice(2)) {
     try {
       printDataResult(command, runLineageDataCommand(command, commandArgs), json2);
     } catch (error) {
-      const message2 = error instanceof Error ? error.message : String(error);
-      if (json2) console.error(JSON.stringify({ ok: false, command, error: message2 }, null, 2));
-      else console.error(`${config.binName}: ${message2}`);
+      const message2 = redactAgentClaimTokens(error instanceof Error ? error.message : String(error));
+      if (json2) {
+        const output = isAgentClaimError(error) ? { ok: false, command, error: error.code, message: message2, conflicts: error.conflicts } : { ok: false, command, error: message2 };
+        console.error(JSON.stringify(output, null, 2));
+      } else console.error(`${config.binName}: ${message2}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+  if (command === "agent") {
+    const commandArgs = normalizedArgs.slice(2);
+    const agentCommand = normalizedArgs[1] || "";
+    const json2 = commandArgs.includes("--json");
+    try {
+      printAgentResult(agentCommand, runLineageAgentCommand(agentCommand, commandArgs), json2);
+    } catch (error) {
+      const message2 = redactAgentClaimTokens(error instanceof Error ? error.message : String(error));
+      if (json2) {
+        const output = isAgentClaimError(error) ? { ok: false, command: `agent ${agentCommand}`, error: error.code, message: message2, conflicts: error.conflicts } : { ok: false, command: `agent ${agentCommand}`, error: message2 };
+        console.error(JSON.stringify(output, null, 2));
+      } else {
+        console.error(`${config.binName}: ${message2}`);
+      }
       process.exit(1);
     }
     process.exit(0);