@mean-weasel/lineage 0.1.15 → 0.1.17

package/dist/cli/lineage.js

@@ -8,6 +8,32 @@ import { dirname as dirname6, join as join10, resolve as resolve8 } from "node:p
 import { spawn } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
+// src/shared/edgeSummary.ts
+var edgeSummaryWordLimit = 2;
+var EdgeSummaryValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "EdgeSummaryValidationError";
+  }
+  code;
+};
+function normalizeEdgeSummary(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string") throw new EdgeSummaryValidationError("not_text", "Edge summary must be text");
+  const words = value.trim().split(/\s+/u).filter(Boolean);
+  if (words.length === 0) return void 0;
+  if (words.length > edgeSummaryWordLimit) {
+    throw new EdgeSummaryValidationError("too_many_words", `Edge summary must contain at most ${edgeSummaryWordLimit} words`);
+  }
+  return words.join(" ");
+}
+function requireEdgeSummary(value) {
+  const summary = normalizeEdgeSummary(value);
+  if (!summary) throw new EdgeSummaryValidationError("required", "Edge summary is required");
+  return summary;
+}
+
 // src/server/agentClaims.ts
 import { createHash as createHash4, randomBytes, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
 
@@ -619,6 +645,7 @@ import { dirname as dirname3, isAbsolute, join as join4, relative as relative2,
 
 // src/shared/lineageProfileTypes.ts
 var lineageProfileSchemaVersion = "lineage.profile.v1";
+var lineageProfileInitSchemaVersion = "lineage.profile_init.v1";
 var lineageProfileDoctorSchemaVersion = "lineage.profile_doctor.v1";
 var lineageProfileCloneReceiptSchemaVersion = "lineage.profile_clone_receipt.v1";
 var lineageProfileAssetsCloneReceiptSchemaVersion = "lineage.profile_assets_clone_receipt.v1";
@@ -654,13 +681,13 @@ function profileManifestPath(selector) {
   if (!profileIdPattern.test(value)) throw new Error(`Invalid profile ID: ${value}`);
   return { manifestPath: join4(lineageProfileRoot(), value, "profile.json"), namedProfileId: value };
 }
-function requiredString(record, key) {
-  const value = record[key];
+function requiredString(record2, key) {
+  const value = record2[key];
   if (typeof value !== "string" || !value.trim()) throw new Error(`Profile manifest requires a non-empty ${key}`);
   return value.trim();
 }
-function optionalString(record, key) {
-  const value = record[key];
+function optionalString(record2, key) {
+  const value = record2[key];
   if (value === void 0) return void 0;
   if (typeof value !== "string" || !value.trim()) throw new Error(`Profile manifest ${key} must be a non-empty string`);
   return value.trim();
@@ -711,15 +738,15 @@ function resolveLineageProfile(selector) {
     throw new Error(`Could not parse profile manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Profile manifest must be a JSON object");
-  const record = raw;
-  const schemaVersion = requiredString(record, "schema_version");
+  const record2 = raw;
+  const schemaVersion = requiredString(record2, "schema_version");
   if (schemaVersion !== lineageProfileSchemaVersion) throw new Error(`Unsupported profile schema_version: ${schemaVersion}`);
-  const profileId = requiredString(record, "profile_id");
+  const profileId = requiredString(record2, "profile_id");
   if (!profileIdPattern.test(profileId)) throw new Error(`Invalid profile ID: ${profileId}`);
   if (namedProfileId && namedProfileId !== profileId) {
     throw new Error(`Named profile ${namedProfileId} does not match immutable manifest profile_id ${profileId}`);
   }
-  const expectedRaw = record.expected_runtime;
+  const expectedRaw = record2.expected_runtime;
   if (expectedRaw !== void 0 && (!expectedRaw || typeof expectedRaw !== "object" || Array.isArray(expectedRaw))) {
     throw new Error("Profile expected_runtime must be an object");
   }
@@ -728,18 +755,18 @@ function resolveLineageProfile(selector) {
   const expectedVersion = expected ? optionalString(expected, "version") : void 0;
   const expectedCodeFingerprint = validateFingerprint(expected ? optionalString(expected, "code_fingerprint") : void 0, "expected_runtime.code_fingerprint");
   const expectedCodeOrigin = validateCodeOrigin(expected?.code_origin);
-  const migrationsRaw = record.required_schema_migrations;
+  const migrationsRaw = record2.required_schema_migrations;
   if (migrationsRaw !== void 0 && (!Array.isArray(migrationsRaw) || migrationsRaw.some((value) => typeof value !== "string" || !value.trim()))) {
     throw new Error("Profile required_schema_migrations must be an array of non-empty strings");
   }
-  const environment = validateEnvironment(requiredString(record, "environment"));
+  const environment = validateEnvironment(requiredString(record2, "environment"));
   const expectedChannel = validateChannel(expected?.channel);
   if (expectedChannel && expectedChannel !== environmentChannel(environment)) {
     throw new Error(`Profile environment ${environment} conflicts with expected runtime channel ${expectedChannel}`);
   }
   const manifest = {
-    asset_root: resolveManifestPath(manifestPath, requiredString(record, "asset_root")),
-    database_path: resolveManifestPath(manifestPath, requiredString(record, "database_path")),
+    asset_root: resolveManifestPath(manifestPath, requiredString(record2, "asset_root")),
+    database_path: resolveManifestPath(manifestPath, requiredString(record2, "database_path")),
     environment,
     ...expected ? {
       expected_runtime: {
@@ -753,7 +780,7 @@ function resolveLineageProfile(selector) {
     profile_id: profileId,
     ...migrationsRaw ? { required_schema_migrations: migrationsRaw.map((value) => value.trim()) } : {},
     schema_version: lineageProfileSchemaVersion,
-    service_origin: validateServiceOrigin(requiredString(record, "service_origin"))
+    service_origin: validateServiceOrigin(requiredString(record2, "service_origin"))
   };
   return { ...manifest, manifest_path: manifestPath, profile_fingerprint: lineageProfileFingerprint(manifest) };
 }
@@ -767,6 +794,120 @@ function lineageProfileFingerprint(profile) {
     service_origin: profile.service_origin
   })).digest("hex");
 }
+function initializeLineageProfile(profileId, serviceOrigin, runtime, confirmWrite, withWriterLease) {
+  if (!confirmWrite) throw new Error("Profile init requires --confirm-write");
+  if (!profileIdPattern.test(profileId)) throw new Error(`Invalid profile ID: ${profileId}`);
+  if (!runtime.code?.verified) throw new Error("Profile init requires a verified runtime code identity");
+  if (runtime.code.origin !== "checkout" && runtime.code.origin !== "package") {
+    throw new Error(`Profile init requires checkout or package code, not ${runtime.code.origin}`);
+  }
+  if (!runtime.code.fingerprint || !/^[a-f0-9]{64}$/i.test(runtime.code.fingerprint)) {
+    throw new Error("Profile init requires a valid executing code fingerprint");
+  }
+  const validatedServiceOrigin = validateServiceOrigin(serviceOrigin);
+  const root = lineageProfileRoot();
+  mkdirSync3(root, { recursive: true, mode: 448 });
+  const profileDirectory = join4(root, profileId);
+  try {
+    mkdirSync3(profileDirectory, { mode: 448 });
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+      const doctor = doctorLineageProfile(profileId, runtime);
+      if (doctor.ok) {
+        throw new Error(`Profile ${profileId} already exists and passes doctor. No files were changed. Reuse it with \`start --profile ${profileId}\`; verify it first with \`profile doctor --profile ${profileId} --json\`.`, { cause: error });
+      }
+      const failures = doctor.checks.filter((check) => check.status === "fail").map((check) => `${check.id}: ${check.message}`).join("; ");
+      throw new Error(`Profile ${profileId} already exists but did not pass doctor. No files were changed. Run \`profile doctor --profile ${profileId} --json\`, then inspect ${profileDirectory} manually before retrying. ${failures}`, { cause: error });
+    }
+    throw error;
+  }
+  const manifestPath = join4(profileDirectory, "profile.json");
+  const databasePath = join4(profileDirectory, "lineage.sqlite");
+  const assetRoot = join4(profileDirectory, "media");
+  const environment = channelEnvironment(runtime.channel);
+  const manifest = {
+    asset_root: assetRoot,
+    database_path: databasePath,
+    environment,
+    expected_runtime: {
+      channel: runtime.channel,
+      code_fingerprint: runtime.code.fingerprint.toLowerCase(),
+      code_origin: runtime.code.origin
+    },
+    profile_id: profileId,
+    schema_version: lineageProfileSchemaVersion,
+    service_origin: validatedServiceOrigin
+  };
+  const profile = {
+    ...manifest,
+    manifest_path: manifestPath,
+    profile_fingerprint: lineageProfileFingerprint(manifest)
+  };
+  try {
+    assertProfileChannel(profile, runtime.channel);
+    assertProfileRuntimePin(profile, runtime);
+    const identity = withWriterLease(profile, () => {
+      mkdirSync3(assetRoot, { mode: 448 });
+      const databaseFd = openSync(databasePath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_RDWR, 384);
+      closeSync(databaseFd);
+      const { DatabaseSync } = require2("node:sqlite");
+      const database = new DatabaseSync(databasePath);
+      let boundIdentity;
+      try {
+        boundIdentity = bindOpenDatabase(database, profile, false);
+      } finally {
+        database.close();
+      }
+      const manifestPayload = {
+        asset_root: "./media",
+        database_path: "./lineage.sqlite",
+        environment: profile.environment,
+        expected_runtime: profile.expected_runtime,
+        profile_id: profile.profile_id,
+        schema_version: profile.schema_version,
+        service_origin: profile.service_origin
+      };
+      writeFileSync2(manifestPath, `${JSON.stringify(manifestPayload, null, 2)}
+`, { encoding: "utf8", flag: "wx", mode: 384 });
+      const manifestFd = openSync(manifestPath, "r");
+      try {
+        fsyncSync(manifestFd);
+      } finally {
+        closeSync(manifestFd);
+      }
+      const directoryFd = openSync(profileDirectory, "r");
+      try {
+        fsyncSync(directoryFd);
+      } finally {
+        closeSync(directoryFd);
+      }
+      const published = resolveLineageProfile(profileId);
+      if (published.profile_fingerprint !== profile.profile_fingerprint) {
+        throw new Error("Initialized profile fingerprint does not match its published manifest");
+      }
+      return boundIdentity;
+    });
+    return {
+      asset_root: profile.asset_root,
+      database_path: profile.database_path,
+      environment: profile.environment,
+      identity,
+      manifest_path: profile.manifest_path,
+      profile_fingerprint: profile.profile_fingerprint,
+      profile_id: profile.profile_id,
+      runtime: {
+        channel: runtime.channel,
+        code_fingerprint: runtime.code.fingerprint,
+        code_origin: runtime.code.origin
+      },
+      schema_version: lineageProfileInitSchemaVersion,
+      service_origin: profile.service_origin
+    };
+  } catch (error) {
+    rmSync(profileDirectory, { force: true, recursive: true });
+    throw error;
+  }
+}
 function sha256(value) {
   return createHash2("sha256").update(value).digest("hex");
 }
@@ -1498,7 +1639,7 @@ function acquireProfileWriterLease(profile, channel, role = "service") {
 }
 function assertProfileWriterLeaseHeld() {
   if (!process.env.LINEAGE_PROFILE) {
-    throw new Error("Persistent writes require a selected named Lineage profile and its writer lease; legacy-unbound access is read-only");
+    throw new Error("Persistent writes require a selected named Lineage profile and its writer lease; legacy-unbound access is read-only. Create a fresh profile with `profile init --profile <id> --confirm-write`, then pass that profile to the command");
   }
   const profileId = process.env.LINEAGE_PROFILE_ID;
   const profileFingerprint = process.env.LINEAGE_PROFILE_FINGERPRINT;
@@ -1622,6 +1763,10 @@ function lineageDb() {
       child_asset_id text not null references assets(id),
       relation_type text not null check (relation_type in ('derived_from')),
       created_at text not null,
+      summary text,
+      summary_created_by text check (summary_created_by in ('human', 'agent', 'system')),
+      summary_updated_by text check (summary_updated_by in ('human', 'agent', 'system')),
+      summary_updated_at text,
       unique (project_id, parent_asset_id, child_asset_id, relation_type)
     );
     create index if not exists edges_parent on asset_edges(project_id, parent_asset_id);
@@ -1905,6 +2050,7 @@ function lineageDb() {
       imported_asset_id text not null references assets(id),
       parent_asset_id text not null references assets(id),
       imported_at text not null,
+      edge_summary text,
       unique(job_id, output_index),
       unique(job_id, file_path)
     );
@@ -1993,6 +2139,11 @@ function lineageDb() {
     );
     create index if not exists agent_claim_events_claim_created on agent_claim_events(claim_id, created_at);
   `);
+  ensureColumn(database, "asset_edges", "summary", "text");
+  ensureColumn(database, "asset_edges", "summary_created_by", "text check (summary_created_by in ('human', 'agent', 'system'))");
+  ensureColumn(database, "asset_edges", "summary_updated_by", "text check (summary_updated_by in ('human', 'agent', 'system'))");
+  ensureColumn(database, "asset_edges", "summary_updated_at", "text");
+  ensureColumn(database, "generation_job_outputs", "edge_summary", "text");
   migrateAssetSelections(database);
   dropLegacyAssetSelectionRootUnique(database);
   ensureColumn(database, "asset_selections", "notes", "text");
@@ -3118,6 +3269,14 @@ function cancelLineageTask(project, fields) {
     database.close();
   }
 }
+function cancelLineageIterateTasksForAssets(project, fields) {
+  const targetIds = fields.assetIds ? new Set(fields.assetIds) : void 0;
+  return listLineageTasks(project, fields.rootAssetId, ["pending"]).tasks.filter((task) => task.task_type === "iterate").filter((task) => !targetIds || targetIds.has(task.target_asset_id)).map((task) => cancelLineageTask(project, {
+    actor: fields.actor,
+    confirmWrite: fields.confirmWrite,
+    taskId: task.id
+  }));
+}
 function resolveLineageTask(project, fields) {
   const normalizedProject = normalizeProject(project);
   const actor = normalizeActor(fields.actor, "Resolve actor");
@@ -3483,6 +3642,23 @@ function rerollRequestId(project, root, node, timestamp) {
 function rowString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
+function lineageEdgeFromRow(row) {
+  const summary = rowString(row.summary);
+  const summaryCreatedBy = rowString(row.summary_created_by);
+  const summaryUpdatedBy = rowString(row.summary_updated_by);
+  const summaryUpdatedAt = rowString(row.summary_updated_at);
+  return {
+    id: String(row.id),
+    parent_asset_id: String(row.parent_asset_id),
+    child_asset_id: String(row.child_asset_id),
+    relation_type: row.relation_type,
+    created_at: String(row.created_at),
+    ...summary ? { summary } : {},
+    ...summaryCreatedBy ? { summary_created_by: summaryCreatedBy } : {},
+    ...summaryUpdatedBy ? { summary_updated_by: summaryUpdatedBy } : {},
+    ...summaryUpdatedAt ? { summary_updated_at: summaryUpdatedAt } : {}
+  };
+}
 function rerollRequestFrom(row) {
   return {
     id: String(row.id),
@@ -3582,6 +3758,9 @@ function localPreviewUrl(project, localPath) {
   return `/api/assets/local-preview?${params.toString()}`;
 }
 function linkLineageAssets(project, fields) {
+  const summary = normalizeEdgeSummary(fields.summary);
+  if (summary && !fields.summaryActor) throw new LineageError("Lineage edge summary requires an explicit author");
+  if (!summary && fields.summaryActor) throw new LineageError("Lineage edge summary author requires a summary");
   const database = lineageDb();
   requireAsset2(database, project, fields.parentAssetId);
   requireAsset2(database, project, fields.childAssetId);
@@ -3600,22 +3779,66 @@ function linkLineageAssets(project, fields) {
     database.close();
     throw error;
   }
+  const createdAt = nowIso();
   const edge = {
     id: edgeId(project, fields.parentAssetId, fields.childAssetId),
     parent_asset_id: fields.parentAssetId,
     child_asset_id: fields.childAssetId,
     relation_type: "derived_from",
-    created_at: nowIso()
+    created_at: createdAt,
+    ...summary ? {
+      summary,
+      summary_created_by: fields.summaryActor,
+      summary_updated_by: fields.summaryActor,
+      summary_updated_at: createdAt
+    } : {}
   };
   if (!fields.confirmWrite) {
     database.close();
     return { ok: true, dryRun: true, edge };
   }
-  database.prepare(`
-    insert into asset_edges (id, project_id, parent_asset_id, child_asset_id, relation_type, created_at)
-    values (?, ?, ?, ?, 'derived_from', ?)
+  const inserted = database.prepare(`
+    insert into asset_edges (
+      id, project_id, parent_asset_id, child_asset_id, relation_type, created_at,
+      summary, summary_created_by, summary_updated_by, summary_updated_at
+    )
+    values (?, ?, ?, ?, 'derived_from', ?, ?, ?, ?, ?)
     on conflict(project_id, parent_asset_id, child_asset_id, relation_type) do nothing
-  `).run(edge.id, project, edge.parent_asset_id, edge.child_asset_id, edge.created_at);
+  `).run(
+    edge.id,
+    project,
+    edge.parent_asset_id,
+    edge.child_asset_id,
+    edge.created_at,
+    edge.summary || null,
+    edge.summary_created_by || null,
+    edge.summary_updated_by || null,
+    edge.summary_updated_at || null
+  );
+  if (inserted.changes === 0) {
+    const existingRow = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+    `).get(project, edge.parent_asset_id, edge.child_asset_id);
+    if (!existingRow) {
+      database.close();
+      throw new LineageError("Lineage edge conflict could not be resolved", 409);
+    }
+    const existingEdge = lineageEdgeFromRow(existingRow);
+    if (summary && (existingEdge.summary !== summary || existingEdge.summary_created_by !== fields.summaryActor || existingEdge.summary_updated_by !== fields.summaryActor || !existingEdge.summary_updated_at)) {
+      database.close();
+      throw new LineageError("Lineage edge already exists with a different summary or provenance", 409);
+    }
+    database.close();
+    return {
+      ok: true,
+      idempotent: true,
+      message: `Already linked ${existingEdge.child_asset_id} from ${existingEdge.parent_asset_id}`,
+      edge: existingEdge
+    };
+  }
   database.close();
   return { ok: true, message: `Linked ${edge.child_asset_id} from ${edge.parent_asset_id}`, edge };
 }
@@ -3627,7 +3850,13 @@ function descendants(database, project, root) {
     const parent = queue.shift();
     if (seen.has(parent)) continue;
     seen.add(parent);
-    const rows = database.prepare("select id, parent_asset_id, child_asset_id, relation_type, created_at from asset_edges where project_id = ? and parent_asset_id = ? order by created_at").all(project, parent);
+    const rows = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and parent_asset_id = ?
+      order by created_at
+    `).all(project, parent).map(lineageEdgeFromRow);
     edges.push(...rows);
     queue.push(...rows.map((row) => row.child_asset_id));
   }
@@ -4013,7 +4242,7 @@ function lineageCommand(command, project, rootAssetId) {
   return `${lineagePublicPackageCommand()} ${command} --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} ${lineageRuntimeSelector()} --json`;
 }
 function linkChildCommand(project, rootAssetId) {
-  return `${lineagePublicPackageCommand()} link-child --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} --child <asset-id> --confirm-write ${lineageRuntimeSelector()} --json`;
+  return `${lineagePublicPackageCommand()} link-child --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} --child <asset-id> --summary "<one-or-two-words>" --confirm-write ${lineageRuntimeSelector()} --json`;
 }
 function rerollImportGuidance(rootAssetId, targetAssetId) {
   return `Use lineage reroll plan --root ${rootAssetId} --target ${targetAssetId} and lineage reroll import instead.`;
@@ -4062,6 +4291,7 @@ function getLineageBrief(project, rootAssetId) {
   };
 }
 function linkSelectedLineageChild(project, fields) {
+  const summary = fields.summaryActor ? requireEdgeSummary(fields.summary) : fields.summary;
   const next = getLineageNextAsset(project, fields.rootAssetId);
   if (!next.next_asset) throw new LineageError("Cannot link child until a next base is selected or unambiguous");
   const rerollRequests = listLineageRerollRequests(project, next.root_asset_id).requests;
@@ -4090,7 +4320,9 @@ function linkSelectedLineageChild(project, fields) {
     childAssetId: fields.childAssetId,
     confirmWrite: fields.confirmWrite,
     claimToken: fields.claimToken,
-    parentAssetId: next.next_asset.asset_id
+    parentAssetId: next.next_asset.asset_id,
+    summary,
+    summaryActor: fields.summaryActor
   });
   return {
     ...result,
@@ -4110,7 +4342,141 @@ function linkSelectedLineageChild(project, fields) {
 import { existsSync as existsSync8, realpathSync as realpathSync2, statSync as statSync4 } from "node:fs";
 import { relative as relative3, resolve as resolve5 } from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
-var adapterVersion = "generation-receipts-v1";
+
+// src/shared/generationOutputManifest.ts
+var generationOutputManifestSchemaVersion = "lineage.generation_output_manifest.v1";
+var GenerationOutputManifestError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GenerationOutputManifestError";
+  }
+};
+function record(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new GenerationOutputManifestError(`${label} must be an object`);
+  }
+  return value;
+}
+function exactKeys(value, allowed, label) {
+  const allowedKeys = new Set(allowed);
+  const unsupported = Object.keys(value).filter((key) => !allowedKeys.has(key)).sort();
+  if (unsupported.length > 0) {
+    throw new GenerationOutputManifestError(`${label} contains unsupported field: ${unsupported[0]}`);
+  }
+}
+function nonEmptyText(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new GenerationOutputManifestError(`${label} is required`);
+  return value.trim();
+}
+function expectedGenerationOutputParents(job) {
+  if (!Number.isInteger(job.expected_output_count) || job.expected_output_count <= 0) {
+    throw new GenerationOutputManifestError("Generation job expected output count must be a positive integer");
+  }
+  const parents = job.inputs.filter((input) => input.role === "lineage_next_base").sort((left, right) => left.position - right.position);
+  if (parents.length === 0) throw new GenerationOutputManifestError("Generation job has no lineage_next_base input");
+  const parentIds = /* @__PURE__ */ new Set();
+  const parentPositions = /* @__PURE__ */ new Set();
+  for (const parent of parents) {
+    if (typeof parent.asset_id !== "string" || !parent.asset_id || parent.asset_id.trim() !== parent.asset_id) {
+      throw new GenerationOutputManifestError("Generation job has invalid lineage parent asset id");
+    }
+    if (!Number.isInteger(parent.position) || parent.position < 0 || parentPositions.has(parent.position)) {
+      throw new GenerationOutputManifestError("Generation job has invalid lineage parent positions");
+    }
+    if (parentIds.has(parent.asset_id)) throw new GenerationOutputManifestError(`Generation job has duplicate lineage parent: ${parent.asset_id}`);
+    parentIds.add(parent.asset_id);
+    parentPositions.add(parent.position);
+  }
+  if (job.expected_output_count % parents.length !== 0) {
+    throw new GenerationOutputManifestError("Generation job has invalid parent mapping");
+  }
+  const outputsPerParent = job.expected_output_count / parents.length;
+  return Array.from({ length: job.expected_output_count }, (_value, outputIndex) => {
+    return parents[Math.floor(outputIndex / outputsPerParent)].asset_id;
+  });
+}
+function createGenerationOutputManifestDraft(job) {
+  return {
+    schema_version: generationOutputManifestSchemaVersion,
+    job_id: job.id,
+    outputs: expectedGenerationOutputParents(job).map((parentAssetId, outputIndex) => ({
+      output_index: outputIndex,
+      file_path: "",
+      parent_asset_id: parentAssetId,
+      edge_summary: ""
+    }))
+  };
+}
+function parseGenerationOutputManifest(value, job, options) {
+  if (!options || typeof options.resolveFilePath !== "function") {
+    throw new GenerationOutputManifestError("Generation output manifest requires a file-path resolver");
+  }
+  const manifest = record(value, "Generation output manifest");
+  exactKeys(manifest, ["schema_version", "job_id", "outputs"], "Generation output manifest");
+  if (manifest.schema_version !== generationOutputManifestSchemaVersion) {
+    throw new GenerationOutputManifestError(`Generation output manifest schema_version must be ${generationOutputManifestSchemaVersion}`);
+  }
+  if (manifest.job_id !== job.id) throw new GenerationOutputManifestError(`Generation output manifest job_id must be ${job.id}`);
+  if (!Array.isArray(manifest.outputs)) throw new GenerationOutputManifestError("Generation output manifest outputs must be an array");
+  const expectedParents = expectedGenerationOutputParents(job);
+  if (manifest.outputs.length !== expectedParents.length) {
+    throw new GenerationOutputManifestError(`Generation output manifest requires ${expectedParents.length} outputs, received ${manifest.outputs.length}`);
+  }
+  const seenIndexes = /* @__PURE__ */ new Set();
+  const outputs = manifest.outputs.map((value2, position) => {
+    const output = record(value2, `Generation output at position ${position}`);
+    exactKeys(output, ["output_index", "file_path", "parent_asset_id", "edge_summary"], `Generation output at position ${position}`);
+    const outputIndex = output.output_index;
+    if (!Number.isInteger(outputIndex) || Number(outputIndex) < 0) {
+      throw new GenerationOutputManifestError(`Generation output at position ${position} requires a non-negative integer output_index`);
+    }
+    const normalizedIndex = Number(outputIndex);
+    if (seenIndexes.has(normalizedIndex)) throw new GenerationOutputManifestError(`Duplicate generation output_index: ${normalizedIndex}`);
+    seenIndexes.add(normalizedIndex);
+    const expectedParent = expectedParents[normalizedIndex];
+    if (!expectedParent) throw new GenerationOutputManifestError(`Unknown generation output_index: ${normalizedIndex}`);
+    const filePath = nonEmptyText(output.file_path, `Generation output ${normalizedIndex} file_path`);
+    const parentAssetId = nonEmptyText(output.parent_asset_id, `Generation output ${normalizedIndex} parent_asset_id`);
+    if (parentAssetId !== expectedParent) {
+      throw new GenerationOutputManifestError(`Generation output ${normalizedIndex} must use parent_asset_id ${expectedParent}`);
+    }
+    let edgeSummary;
+    try {
+      edgeSummary = requireEdgeSummary(output.edge_summary);
+    } catch (error) {
+      if (error instanceof EdgeSummaryValidationError) {
+        throw new GenerationOutputManifestError(`Generation output ${normalizedIndex}: ${error.message}`);
+      }
+      throw error;
+    }
+    return {
+      output_index: normalizedIndex,
+      file_path: filePath,
+      parent_asset_id: parentAssetId,
+      edge_summary: edgeSummary
+    };
+  });
+  for (const outputIndex of expectedParents.keys()) {
+    if (!seenIndexes.has(outputIndex)) throw new GenerationOutputManifestError(`Missing generation output_index: ${outputIndex}`);
+  }
+  outputs.sort((left, right) => left.output_index - right.output_index);
+  const seenPaths = /* @__PURE__ */ new Set();
+  const resolvedOutputs = outputs.map((output) => {
+    const filePath = nonEmptyText(options.resolveFilePath(output.file_path), `Generation output ${output.output_index} resolved file_path`);
+    if (seenPaths.has(filePath)) throw new GenerationOutputManifestError(`Duplicate generation output file_path: ${filePath}`);
+    seenPaths.add(filePath);
+    return { ...output, file_path: filePath };
+  });
+  return {
+    schema_version: generationOutputManifestSchemaVersion,
+    job_id: job.id,
+    outputs: resolvedOutputs
+  };
+}
+
+// src/server/generationReceipts.ts
+var legacyAdapterVersion = "generation-receipts-v1";
+var manifestAdapterVersion = "generation-receipts-v2";
 var provider = "codex-handoff";
 var GenerationReceiptError = class extends Error {
   constructor(message, status = 400) {
@@ -4129,6 +4495,70 @@ function parseJson(value, fallback) {
   if (!value) return fallback;
   return JSON.parse(value);
 }
+function positiveInteger(value) {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+function resolveLineageSelection(project) {
+  const rootAssetId = activeLineageWorkspaceRoot(project);
+  if (!rootAssetId) throw new GenerationReceiptError("No active lineage workspace for generation planning");
+  const next = getLineageNextAsset(project, rootAssetId);
+  if (!next.next_asset) throw new GenerationReceiptError(`No clear lineage next asset: ${next.reason}`);
+  if (next.strategy !== "selected") throw new GenerationReceiptError("Generation v1 requires an explicit selected lineage next base");
+  if (next.selection_mode !== "multiple" && next.selection?.asset_id !== next.next_asset.asset_id) throw new GenerationReceiptError("Generation v1 requires one explicit selected lineage next base");
+  return next;
+}
+function selectedParents(next) {
+  const parents = next.next_assets.length > 0 ? next.next_assets : next.next_asset ? [next.next_asset] : [];
+  if (parents.length === 0) throw new GenerationReceiptError("Missing lineage next base");
+  return parents;
+}
+function parentMappings(next, perBaseCount) {
+  return selectedParents(next).map((parent, parentIndex) => ({
+    parent,
+    output_indexes: Array.from({ length: perBaseCount }, (_value, index) => parentIndex * perBaseCount + index)
+  }));
+}
+function buildHandoff(project, id, prompt, count, perBaseCount, next, inputs) {
+  const parent = next.next_asset;
+  if (!parent) throw new GenerationReceiptError("Missing lineage next base");
+  const parents = parentMappings(next, perBaseCount);
+  const outputManifest = createGenerationOutputManifestDraft({ id, expected_output_count: count, inputs });
+  const importCommand = `${lineagePublicPackageCommand()} generate image import --project ${quote(project)} --job-id ${quote(id)} --manifest ${quote(".asset-scratch/generation-output-manifest.json")} --confirm-write ${lineageRuntimeSelector()} --json`;
+  return {
+    schema_version: "lineage.generation_handoff.v2",
+    provider,
+    project,
+    job_id: id,
+    prompt,
+    expected_output_count: count,
+    per_base_count: next.selection_mode === "multiple" ? perBaseCount : void 0,
+    lineage: {
+      root_asset_id: next.root_asset_id,
+      parent_asset_id: parent.asset_id,
+      selection_strategy: next.strategy,
+      parent_title: parent.title,
+      parent_local_path: parent.local_path,
+      parent_s3_key: parent.s3_key,
+      parents: parents.length > 1 ? parents.map((mapping) => ({
+        parent_asset_id: mapping.parent.asset_id,
+        parent_title: mapping.parent.title,
+        parent_local_path: mapping.parent.local_path,
+        parent_s3_key: mapping.parent.s3_key,
+        output_indexes: mapping.output_indexes
+      })) : void 0
+    },
+    instructions: [
+      "Use Codex image generation outside Lineage server code.",
+      "Write generated output files under .asset-scratch before import.",
+      "Do not call live provider APIs from the CLI or server.",
+      "Fill every output_manifest entry with its generated file path and a one- or two-word edge summary.",
+      "Import the completed manifest with --confirm-write to persist every lineage child."
+    ],
+    import_command: importCommand,
+    output_manifest: outputManifest,
+    guardrails: { live_generation: false, external_services: false, output_root: ".asset-scratch", confirm_write_required: true }
+  };
+}
 function buildRerollHandoff(project, id, prompt, rootAssetId, target, request) {
   const importCommand = `${lineagePublicPackageCommand()} reroll import --project ${quote(project)} --job-id ${quote(id)} --file <.asset-scratch-file> --confirm-write ${lineageRuntimeSelector()} --json`;
   return {
@@ -4157,6 +4587,19 @@ function buildRerollHandoff(project, id, prompt, rootAssetId, target, request) {
     guardrails: { live_generation: false, external_services: false, output_root: ".asset-scratch", confirm_write_required: true }
   };
 }
+function inputsFrom(jobIdValue, project, next) {
+  return selectedParents(next).map((parent, position) => ({
+    id: `${jobIdValue}:input:${position}`,
+    job_id: jobIdValue,
+    project_id: project,
+    asset_id: parent.asset_id,
+    root_asset_id: next.root_asset_id,
+    role: "lineage_next_base",
+    position,
+    selection_strategy: next.strategy,
+    selection_snapshot: next
+  }));
+}
 function receiptFrom(row) {
   return {
     id: String(row.id),
@@ -4169,6 +4612,7 @@ function receiptFrom(row) {
   };
 }
 function outputFrom(row) {
+  const edgeSummary = typeof row.edge_summary === "string" && row.edge_summary.length > 0 ? row.edge_summary : void 0;
   return {
     id: String(row.id),
     job_id: String(row.job_id),
@@ -4180,7 +4624,8 @@ function outputFrom(row) {
     content_type: String(row.content_type),
     imported_asset_id: String(row.imported_asset_id),
     parent_asset_id: String(row.parent_asset_id),
-    imported_at: String(row.imported_at)
+    imported_at: String(row.imported_at),
+    ...edgeSummary ? { edge_summary: edgeSummary } : {}
   };
 }
 function loadGenerationJob(database, project, id) {
@@ -4226,6 +4671,72 @@ function insertReceipt(database, id, type, command, payload) {
     values (?, ?, ?, 'ok', ?, ?, ?)
   `).run(`${id}:receipt:${type}:${Date.now()}`, id, type, command, JSON.stringify(payload), nowIso());
 }
+function planImageGeneration(project = defaultProject, fields) {
+  const prompt = fields.prompt.trim();
+  if (!prompt) throw new GenerationReceiptError("Missing --prompt");
+  if (!fields.fromLineageSelection) throw new GenerationReceiptError("Generation v1 requires --from-lineage-selection");
+  const next = resolveLineageSelection(project);
+  const parentCount = selectedParents(next).length;
+  if (parentCount > 1 && !positiveInteger(fields.perBaseCount)) throw new GenerationReceiptError("Multi-parent generation requires --per-base-count");
+  const perBaseCount = parentCount > 1 ? Number(fields.perBaseCount) : Number(fields.count ?? fields.perBaseCount);
+  const count = parentCount * perBaseCount;
+  if (!positiveInteger(perBaseCount)) throw new GenerationReceiptError("Generation count must be a positive integer");
+  if (fields.count !== void 0 && fields.count !== count) throw new GenerationReceiptError(`Generation count mismatch: expected ${count} from selected bases, received ${fields.count}`);
+  const id = jobId();
+  const inputs = inputsFrom(id, project, next);
+  const handoff = buildHandoff(project, id, prompt, count, perBaseCount, next, inputs);
+  const mappings = parentMappings(next, perBaseCount).map((mapping) => ({ parent_asset_id: mapping.parent.asset_id, output_indexes: mapping.output_indexes }));
+  const timestamp = nowIso();
+  const preview = {
+    id,
+    project_id: project,
+    provider,
+    adapter_version: manifestAdapterVersion,
+    source_mode: "lineage_selection",
+    root_asset_id: next.root_asset_id,
+    prompt,
+    expected_output_count: count,
+    status: "planned",
+    output_dir: ".asset-scratch",
+    handoff,
+    created_at: timestamp,
+    updated_at: timestamp,
+    inputs,
+    outputs: [],
+    receipts: [{
+      id: `${id}:receipt:plan:preview`,
+      job_id: id,
+      receipt_type: "plan",
+      status: "ok",
+      command: "generate image plan",
+      payload: { prompt, expected_output_count: count, per_base_count: parentCount > 1 ? perBaseCount : void 0, lineage: handoff.lineage, parent_mappings: mappings },
+      created_at: timestamp
+    }]
+  };
+  if (fields.dryRun) return { ok: true, command: "generate image plan", project, dryRun: true, wouldWrite: true, job: preview };
+  const database = lineageDb();
+  try {
+    database.exec("BEGIN IMMEDIATE");
+    try {
+      database.prepare(`
+        insert into generation_jobs (
+          id, project_id, provider, adapter_version, source_mode, root_asset_id, prompt,
+          expected_output_count, status, output_dir, handoff_json, created_at, updated_at
+        ) values (?, ?, ?, ?, 'lineage_selection', ?, ?, ?, 'planned', ?, ?, ?, ?)
+      `).run(id, project, provider, manifestAdapterVersion, next.root_asset_id, prompt, count, ".asset-scratch", JSON.stringify(handoff), timestamp, timestamp);
+      const insertInput = database.prepare("insert into generation_job_inputs (id, job_id, project_id, asset_id, root_asset_id, role, position, selection_strategy, selection_snapshot_json) values (?, ?, ?, ?, ?, ?, ?, ?, ?)");
+      for (const input of inputs) insertInput.run(input.id, id, project, input.asset_id, input.root_asset_id, input.role, input.position, input.selection_strategy, JSON.stringify(next));
+      insertReceipt(database, id, "plan", "generate image plan", preview.receipts[0].payload);
+      database.exec("COMMIT");
+    } catch (error) {
+      database.exec("ROLLBACK");
+      throw error;
+    }
+    return { ok: true, command: "generate image plan", project, job: loadGenerationJob(database, project, id) };
+  } finally {
+    database.close();
+  }
+}
 function planImageReroll(project = defaultProject, fields) {
   const prompt = fields.prompt.trim();
   if (!prompt) throw new GenerationReceiptError("Missing --prompt");
@@ -4270,7 +4781,7 @@ function planImageReroll(project = defaultProject, fields) {
     id,
     project_id: project,
     provider,
-    adapter_version: adapterVersion,
+    adapter_version: legacyAdapterVersion,
     source_mode: "lineage_reroll",
     root_asset_id: snapshot.root_asset_id,
     prompt,
@@ -4302,7 +4813,7 @@ function planImageReroll(project = defaultProject, fields) {
           id, project_id, provider, adapter_version, source_mode, root_asset_id, prompt,
           expected_output_count, status, output_dir, handoff_json, created_at, updated_at
         ) values (?, ?, ?, ?, 'lineage_reroll', ?, ?, 1, 'planned', ?, ?, ?, ?)
-      `).run(id, project, provider, adapterVersion, snapshot.root_asset_id, prompt, ".asset-scratch", JSON.stringify(handoff), timestamp, timestamp);
+      `).run(id, project, provider, legacyAdapterVersion, snapshot.root_asset_id, prompt, ".asset-scratch", JSON.stringify(handoff), timestamp, timestamp);
       database.prepare("insert into generation_job_inputs (id, job_id, project_id, asset_id, root_asset_id, role, position, selection_strategy, selection_snapshot_json) values (?, ?, ?, ?, ?, ?, ?, ?, ?)").run(input.id, id, project, input.asset_id, input.root_asset_id, input.role, input.position, input.selection_strategy, JSON.stringify(input.selection_snapshot));
       insertReceipt(database, id, "plan", "reroll plan", preview.receipts[0].payload);
       database.exec("COMMIT");
@@ -4315,14 +4826,66 @@ function planImageReroll(project = defaultProject, fields) {
     database.close();
   }
 }
+function parentForOutput(job, outputIndex) {
+  const inputs = job.inputs.filter((input) => input.role === "lineage_next_base");
+  if (inputs.length === 0) throw new GenerationReceiptError("Generation job has no lineage_next_base input");
+  if (inputs.length === 1) return inputs[0].asset_id;
+  if (job.expected_output_count % inputs.length !== 0) throw new GenerationReceiptError("Generation job has invalid parent mapping");
+  return inputs[Math.floor(outputIndex / (job.expected_output_count / inputs.length))]?.asset_id || inputs[inputs.length - 1].asset_id;
+}
+function parentInputs(job) {
+  const inputs = job.inputs.filter((input) => input.role === "lineage_next_base");
+  if (inputs.length === 0) throw new GenerationReceiptError("Generation job has no lineage_next_base input");
+  return inputs;
+}
+function parentFilesFor(job, parentFiles) {
+  const inputs = parentInputs(job);
+  const expectedPerParent = job.expected_output_count / inputs.length;
+  if (!Number.isInteger(expectedPerParent)) throw new GenerationReceiptError("Generation job has invalid parent mapping");
+  const allowedParents = new Set(inputs.map((input) => input.asset_id));
+  const seenParents = /* @__PURE__ */ new Set();
+  const mapped = [];
+  for (const parentAssetId of Object.keys(parentFiles)) {
+    if (!allowedParents.has(parentAssetId)) throw new GenerationReceiptError(`Unknown generation parent mapping: ${parentAssetId}`);
+    if (seenParents.has(parentAssetId)) throw new GenerationReceiptError(`Duplicate generation parent mapping: ${parentAssetId}`);
+    seenParents.add(parentAssetId);
+  }
+  for (const input of inputs) {
+    const files = (parentFiles[input.asset_id] || []).map((file) => file.trim()).filter(Boolean);
+    if (files.length === 0) throw new GenerationReceiptError(`Missing generation parent mapping for ${input.asset_id}`);
+    if (files.length !== expectedPerParent) throw new GenerationReceiptError(`Parent ${input.asset_id} requires ${expectedPerParent} output file${expectedPerParent === 1 ? "" : "s"}, received ${files.length}`);
+    for (const file of files) mapped.push({ file, parentAssetId: input.asset_id });
+  }
+  return mapped;
+}
+function orderedFilesFor(job, files) {
+  return files.map((file, index) => ({ file, parentAssetId: parentForOutput(job, index) }));
+}
+function inspectImageGeneration(project = defaultProject, jobIdValue) {
+  if (!jobIdValue) throw new GenerationReceiptError("Missing --job-id");
+  const database = lineageDb();
+  try {
+    return { ok: true, command: "generate image inspect", project, job: loadGenerationJob(database, project, jobIdValue) };
+  } finally {
+    database.close();
+  }
+}
 function isPathInside(child, parent) {
   const rel = relative3(parent, child);
   return Boolean(rel) && !rel.startsWith("..") && !rel.startsWith("/");
 }
-function resolveScratchFile(file) {
+function scratchCandidate(file) {
   const scratchRoot = resolve5(repoRoot, ".asset-scratch");
   const candidate = file.startsWith(".asset-scratch/") || resolve5(file).startsWith(scratchRoot) ? resolve5(repoRoot, file) : resolve5(scratchRoot, file);
   if (!isPathInside(candidate, scratchRoot)) throw new GenerationReceiptError(`Import file must be under .asset-scratch: ${file}`);
+  return { candidate, scratchRoot };
+}
+function resolveScratchManifestPath(file) {
+  const { candidate, scratchRoot } = scratchCandidate(file);
+  return relative3(scratchRoot, candidate);
+}
+function resolveScratchFile(file) {
+  const { candidate, scratchRoot } = scratchCandidate(file);
   if (!existsSync8(candidate)) throw new GenerationReceiptError(`Missing import file: ${file}`, 404);
   const realScratchRoot = realpathSync2(scratchRoot);
   const realCandidate = realpathSync2(candidate);
@@ -4338,6 +4901,165 @@ function resolveScratchFile(file) {
     assetId: `local-${checksum.slice(0, 12)}`
   };
 }
+function generationManifestConflict() {
+  throw new GenerationReceiptError("Generation import already exists with different output, summary, or provenance", 409);
+}
+function confirmManifestRetry(project, job, manifest) {
+  if (job.outputs.length !== manifest.outputs.length) generationManifestConflict();
+  const database = lineageDb();
+  try {
+    for (const expected of manifest.outputs) {
+      const recorded = job.outputs.find((output) => output.output_index === expected.output_index);
+      if (!recorded || recorded.file_path !== expected.file_path || recorded.parent_asset_id !== expected.parent_asset_id || recorded.edge_summary !== expected.edge_summary) generationManifestConflict();
+      const edge = database.prepare(`
+        select summary, summary_created_by, summary_updated_by, summary_updated_at
+        from asset_edges
+        where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+      `).get(project, recorded.parent_asset_id, recorded.imported_asset_id);
+      if (!edge || edge.summary !== expected.edge_summary || edge.summary_created_by !== "agent" || edge.summary_updated_by !== "agent" || typeof edge.summary_updated_at !== "string" || edge.summary_updated_at.length === 0) generationManifestConflict();
+    }
+    return { ok: true, command: "generate image import", project, job, imported: job.outputs, idempotent: true };
+  } finally {
+    database.close();
+  }
+}
+function importImageGenerationOutputs(project = defaultProject, fields) {
+  if (!fields.jobId) throw new GenerationReceiptError("Missing --job-id");
+  if (!fields.confirmWrite) throw new GenerationReceiptError("Generation import requires --confirm-write");
+  const database = lineageDb();
+  let job;
+  try {
+    job = loadGenerationJob(database, project, fields.jobId);
+  } finally {
+    database.close();
+  }
+  if (job.source_mode !== "lineage_selection") throw new GenerationReceiptError(`Generation job is not an image-selection job: ${job.source_mode}`);
+  const hasManifestInput = fields.manifest !== void 0;
+  const hasParentFilesInput = fields.parentFiles !== void 0;
+  const hasFilesInput = fields.files !== void 0;
+  if (hasManifestInput && (hasParentFilesInput || hasFilesInput)) {
+    throw new GenerationReceiptError("Use --manifest or legacy --files/--parent-files, not both");
+  }
+  if (hasParentFilesInput && hasFilesInput) throw new GenerationReceiptError("Use --files or --parent-files, not both");
+  let manifest;
+  let parentFileRows;
+  let mappingStrategy;
+  if (job.adapter_version === manifestAdapterVersion) {
+    if (!hasManifestInput) throw new GenerationReceiptError("New generation jobs require --manifest");
+    manifest = parseGenerationOutputManifest(fields.manifest, job, { resolveFilePath: resolveScratchManifestPath });
+    if (job.status === "imported") return confirmManifestRetry(project, job, manifest);
+    if (job.status !== "planned") throw new GenerationReceiptError(`Generation job is not importable from status: ${job.status}`);
+    parentFileRows = manifest.outputs.map((output) => ({
+      edgeSummary: output.edge_summary,
+      file: output.file_path,
+      parentAssetId: output.parent_asset_id
+    }));
+    mappingStrategy = "generation_output_manifest_v1";
+  } else if (job.adapter_version === legacyAdapterVersion) {
+    if (hasManifestInput) throw new GenerationReceiptError("Already-planned legacy generation jobs require --files or --parent-files");
+    if (job.status !== "planned") throw new GenerationReceiptError(`Generation job is not importable from status: ${job.status}`);
+    const hasExplicitParentFiles = Boolean(fields.parentFiles && Object.keys(fields.parentFiles).length > 0);
+    parentFileRows = hasExplicitParentFiles ? parentFilesFor(job, fields.parentFiles || {}) : orderedFilesFor(job, (fields.files || []).map((file) => file.trim()).filter(Boolean));
+    mappingStrategy = hasExplicitParentFiles ? "explicit_parent_files" : "ordered_per_base";
+  } else {
+    throw new GenerationReceiptError(`Unsupported generation adapter version: ${job.adapter_version}`);
+  }
+  if (parentFileRows.length === 0) throw new GenerationReceiptError("Generation import requires --files or --parent-files");
+  if (parentFileRows.length !== job.expected_output_count) {
+    throw new GenerationReceiptError(`Output count mismatch: expected ${job.expected_output_count}, received ${parentFileRows.length}`);
+  }
+  const resolved = parentFileRows.map((row) => ({ ...resolveScratchFile(row.file), edgeSummary: row.edgeSummary, parentAssetId: row.parentAssetId }));
+  const uniquePaths = new Set(resolved.map((file) => file.relativePath));
+  if (uniquePaths.size !== resolved.length) throw new GenerationReceiptError("Generation import files must be unique");
+  cancelLineageIterateTasksForAssets(project, {
+    actor: "system",
+    confirmWrite: false,
+    rootAssetId: job.root_asset_id
+  });
+  indexLineageAssets(project);
+  const writeDb = lineageDb();
+  try {
+    const timestamp = nowIso();
+    writeDb.exec("BEGIN IMMEDIATE");
+    try {
+      for (const [index, file] of resolved.entries()) {
+        const assetRow = writeDb.prepare("select id from assets where project_id = ? and id = ?").get(project, file.assetId);
+        if (!assetRow) throw new GenerationReceiptError(`Indexed local asset was not found: ${file.relativePath}`);
+        const outputId = `${fields.jobId}:output:${index}`;
+        writeDb.prepare(`insert into generation_job_outputs (
+          id, job_id, project_id, output_index, file_path, checksum_sha256, size_bytes, content_type,
+          imported_asset_id, parent_asset_id, imported_at, edge_summary
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+          outputId,
+          fields.jobId,
+          project,
+          index,
+          file.relativePath,
+          file.checksum,
+          file.size,
+          file.contentType,
+          file.assetId,
+          file.parentAssetId,
+          timestamp,
+          file.edgeSummary || null
+        );
+        const insertedEdge = writeDb.prepare(`insert into asset_edges (
+          id, project_id, parent_asset_id, child_asset_id, relation_type, created_at,
+          summary, summary_created_by, summary_updated_by, summary_updated_at
+        ) values (?, ?, ?, ?, 'derived_from', ?, ?, ?, ?, ?)
+        on conflict(project_id, parent_asset_id, child_asset_id, relation_type) do nothing`).run(
+          `${project}:${file.parentAssetId}:derived_from:${file.assetId}`,
+          project,
+          file.parentAssetId,
+          file.assetId,
+          timestamp,
+          file.edgeSummary || null,
+          file.edgeSummary ? "agent" : null,
+          file.edgeSummary ? "agent" : null,
+          file.edgeSummary ? timestamp : null
+        );
+        if (file.edgeSummary && insertedEdge.changes === 0) {
+          const edge = writeDb.prepare(`
+            select summary, summary_created_by, summary_updated_by, summary_updated_at
+            from asset_edges
+            where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+          `).get(project, file.parentAssetId, file.assetId);
+          if (!edge || edge.summary !== file.edgeSummary || edge.summary_created_by !== "agent" || edge.summary_updated_by !== "agent" || typeof edge.summary_updated_at !== "string" || edge.summary_updated_at.length === 0) generationManifestConflict();
+        }
+      }
+      writeDb.prepare(`
+        update generation_jobs
+        set status = 'imported', imported_at = ?, updated_at = ?
+        where project_id = ? and id = ?
+      `).run(timestamp, timestamp, project, fields.jobId);
+      insertReceipt(writeDb, fields.jobId, "import", "generate image import", {
+        mapping_strategy: mappingStrategy,
+        files: resolved.map((file, index) => ({
+          output_index: index,
+          file_path: file.relativePath,
+          imported_asset_id: file.assetId,
+          parent_asset_id: file.parentAssetId,
+          ...file.edgeSummary ? { edge_summary: file.edgeSummary } : {}
+        })),
+        selection_reset: { root_asset_id: job.root_asset_id, cleared: true }
+      });
+      writeDb.prepare("delete from asset_selections where project_id = ? and root_asset_id = ?").run(project, job.root_asset_id);
+      writeDb.exec("COMMIT");
+    } catch (error) {
+      writeDb.exec("ROLLBACK");
+      throw error;
+    }
+    cancelLineageIterateTasksForAssets(project, {
+      actor: "system",
+      confirmWrite: true,
+      rootAssetId: job.root_asset_id
+    });
+    const importedJob = loadGenerationJob(writeDb, project, fields.jobId);
+    return { ok: true, command: "generate image import", project, job: importedJob, imported: importedJob.outputs };
+  } finally {
+    writeDb.close();
+  }
+}
 function importImageRerollOutput(project = defaultProject, fields) {
   if (!fields.jobId) throw new GenerationReceiptError("Missing --job-id");
   if (!fields.confirmWrite) throw new GenerationReceiptError("Generation import requires --confirm-write");
@@ -5178,6 +5900,9 @@ function getLineageRuntimeInfo(options = {}) {
   const code = options.code || getLineageCodeIdentity(channel);
   const databaseInfo = { exists: existsSync10(dbPath), path: dbPath };
   const schema = { migration_keys: [] };
+  const serviceInstanceId = process.env.LINEAGE_SERVICE_INSTANCE_ID;
+  const launcherPid = process.env.LINEAGE_LAUNCHER_PID ? Number(process.env.LINEAGE_LAUNCHER_PID) : void 0;
+  const isServiceProcess = Boolean(serviceInstanceId && Number.isInteger(launcherPid) && launcherPid > 0);
   if (databaseInfo.exists) {
     try {
       const stat = statSync6(dbPath);
@@ -5215,14 +5940,22 @@ function getLineageRuntimeInfo(options = {}) {
     git_sha: code.git_sha,
     node_env: process.env.NODE_ENV,
     package_name: info.name,
-    profile: runtimeProfileIdentity(channel),
-    schema,
-    service: {
-      instance_id: process.env.LINEAGE_SERVICE_INSTANCE_ID,
-      launcher_pid: process.env.LINEAGE_LAUNCHER_PID ? Number(process.env.LINEAGE_LAUNCHER_PID) : void 0,
+    process: {
       pid: process.pid,
+      role: isServiceProcess ? "service" : "command",
       started_at: processStartedAt
     },
+    profile: runtimeProfileIdentity(channel),
+    schema,
+    ...isServiceProcess ? {
+      service: {
+        instance_id: serviceInstanceId,
+        launcher_pid: launcherPid,
+        mode: process.env.LINEAGE_SERVICE_MODE === "managed" ? "managed" : "foreground",
+        pid: process.pid,
+        started_at: processStartedAt
+      }
+    } : {},
     version: info.version
   };
 }
@@ -5241,22 +5974,23 @@ var ManagedWriterRoutingError = class extends Error {
   status;
 };
 function managedWriterTimeoutMs(command, args) {
-  const subcommand = args.find((arg) => !arg.startsWith("-")) || "";
-  return command === "reroll" && subcommand === "import" ? 5 * 6e4 : 3e4;
+  const positions = args.filter((arg) => !arg.startsWith("-"));
+  const slowImport = command === "reroll" && positions[0] === "import" || command === "generate" && positions[0] === "image" && positions[1] === "import";
+  return slowImport ? 5 * 6e4 : 3e4;
 }
 function errorMessage(body, fallback) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return fallback;
-  const record = body;
-  if (typeof record.message === "string") return record.message;
-  if (typeof record.error === "string") return record.error;
+  const record2 = body;
+  if (typeof record2.message === "string") return record2.message;
+  if (typeof record2.error === "string") return record2.error;
   return fallback;
 }
 function agentClaimError(body, status) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
-  const record = body;
-  if (typeof record.message !== "string" || typeof record.error !== "string") return void 0;
-  const conflicts = Array.isArray(record.conflicts) ? record.conflicts : [];
-  return new AgentClaimError(record.message, status, record.error, conflicts);
+  const record2 = body;
+  if (typeof record2.message !== "string" || typeof record2.error !== "string") return void 0;
+  const conflicts = Array.isArray(record2.conflicts) ? record2.conflicts : [];
+  return new AgentClaimError(record2.message, status, record2.error, conflicts);
 }
 function assertResponseIdentity(body, profile, channel) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
@@ -5354,7 +6088,30 @@ function readOptions(args, name) {
   }
   return values;
 }
+function readJsonFile(path, label) {
+  try {
+    return JSON.parse(readFileSync6(resolve8(path), "utf8"));
+  } catch (error) {
+    throw new Error(`${label} must be a readable JSON file: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+function parentFilesOption(value) {
+  if (value === void 0) return void 0;
+  const mappings = {};
+  for (const rawMapping of value.split(";")) {
+    const separator = rawMapping.indexOf("=");
+    const parent = separator >= 0 ? rawMapping.slice(0, separator).trim() : "";
+    const files = separator >= 0 ? rawMapping.slice(separator + 1).split(",").map((file) => file.trim()).filter(Boolean) : [];
+    if (!parent || files.length === 0) throw new Error("lineage generate image import --parent-files requires parent=file[,file][;parent=file]");
+    if (Object.hasOwn(mappings, parent)) throw new Error(`Duplicate generation parent mapping: ${parent}`);
+    mappings[parent] = files;
+  }
+  return mappings;
+}
 function resolveStartOptions(config, args) {
+  if (!profileSelector(args)) {
+    throw new Error("Start requires --profile or LINEAGE_PROFILE. Create one with `profile init --profile <id> --confirm-write`, then start again with that profile");
+  }
   const profile = prepareCliProfile(config, args);
   const serviceUrl = profile ? new URL(profile.service_origin) : void 0;
   const rawPort = readOption(args, "--port") || process.env.PORT || serviceUrl?.port || String(config.defaultPort);
@@ -5434,7 +6191,8 @@ function formatLineageHelp(config) {
   return `${config.binName} ${packageVersion()}
 
 Usage:
-  ${config.binName} start [--profile <id-or-manifest>] [--port <port>] [--host <host>] [--db <path>] [--asset-root <path>] [--open] [--json]
+  ${config.binName} start --profile <id-or-manifest> [--open] [--json]
+  ${config.binName} profile init --profile <new-profile-id> [--service-origin <http-origin>] --confirm-write [--json]
   ${config.binName} profile doctor --profile <id-or-manifest> [--json]
   ${config.binName} profile bind --profile <id-or-manifest> --confirm-write [--json]
   ${config.binName} profile clone --source-db <snapshot-source> --target-profile <id-or-manifest> --confirm-write [--json]
@@ -5446,7 +6204,11 @@ Usage:
   ${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} selection packet [--project <project>] [--workspace <id-or-root>|--root <asset-id>] [--channel <channel>] [--campaign <campaign>] [--context-notes <text>] [--label <label>] [--schema v2] [--out <path>] [--strict] [--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} link-child --root <asset-id> --child <asset-id> --summary "<one-or-two-words>" [--project <project>] [--claim-token <claim-id.secret>] [--confirm-write] [--db <path>] [--json]
+  ${config.binName} generate image plan --prompt <text> --from-lineage-selection [--count <count>|--per-base-count <count>] [--project <project>] [--dry-run] [--db <path>] [--json]
+  ${config.binName} generate image inspect --job-id <job-id> [--project <project>] [--db <path>] [--json]
+  ${config.binName} generate image import --job-id <job-id> --manifest <json-file> --confirm-write [--project <project>] [--db <path>] [--json]
+  ${config.binName} generate image import --job-id <legacy-job-id> (--files <file,file>|--parent-files <parent=file;parent=file>) --confirm-write [--project <project>] [--db <path>] [--json]
   ${config.binName} reroll list --root <asset-id> [--project <project>] [--db <path>] [--json]
   ${config.binName} reroll mark --root <asset-id> --target <asset-id> [--notes <text>] [--requested-by agent|human|system] [--project <project>] [--confirm-write] [--db <path>] [--json]
   ${config.binName} reroll cancel --root <asset-id> --target <asset-id> [--project <project>] [--confirm-write] [--db <path>] [--json]
@@ -5568,7 +6330,8 @@ function resolveDataCommandOptions(args) {
     dbPath: readOption(args, "--db"),
     json: args.includes("--json"),
     project: readOption(args, "--project") || process.env.LINEAGE_DEFAULT_PRODUCT || defaultProduct,
-    rootAssetId: readOption(args, "--root")
+    rootAssetId: readOption(args, "--root"),
+    summary: readOption(args, "--summary")
   };
   if (options.dbPath) process.env.LINEAGE_DB = options.dbPath;
   return options;
@@ -5611,13 +6374,57 @@ function runLineageDataCommand(command, args) {
   }
   if (command === "link-child") {
     if (!options.childAssetId) throw new Error("lineage link-child requires --child");
+    const summary = requireEdgeSummary(options.summary);
     return linkSelectedLineageChild(options.project, {
       childAssetId: options.childAssetId,
       claimToken: options.claimToken,
       confirmWrite: options.confirmWrite,
-      rootAssetId: options.rootAssetId || options.assetId
+      rootAssetId: options.rootAssetId || options.assetId,
+      summary,
+      summaryActor: "agent"
     });
   }
+  if (command === "generate") {
+    const [resource, subcommand] = positionalArgs(args);
+    if (resource !== "image") throw new Error(`Unknown generate command: ${resource}`);
+    if (subcommand === "plan") {
+      const prompt = readOption(args, "--prompt");
+      const rawCount = readOption(args, "--count");
+      const rawPerBaseCount = readOption(args, "--per-base-count");
+      if (!prompt) throw new Error("lineage generate image plan requires --prompt");
+      return planImageGeneration(options.project, {
+        count: rawCount === void 0 ? void 0 : Number(rawCount),
+        dryRun: args.includes("--dry-run"),
+        fromLineageSelection: args.includes("--from-lineage-selection"),
+        perBaseCount: rawPerBaseCount === void 0 ? void 0 : Number(rawPerBaseCount),
+        prompt
+      });
+    }
+    if (subcommand === "inspect") {
+      const jobId2 = readOption(args, "--job-id");
+      if (!jobId2) throw new Error("lineage generate image inspect requires --job-id");
+      return inspectImageGeneration(options.project, jobId2);
+    }
+    if (subcommand === "import") {
+      const jobId2 = readOption(args, "--job-id");
+      const manifestPath = readOption(args, "--manifest");
+      const filesValue = readOption(args, "--files");
+      const parentFilesValue = readOption(args, "--parent-files");
+      if (!jobId2) throw new Error("lineage generate image import requires --job-id");
+      if (manifestPath !== void 0 && (filesValue !== void 0 || parentFilesValue !== void 0)) {
+        throw new Error("Use --manifest or legacy --files/--parent-files, not both");
+      }
+      if (filesValue !== void 0 && parentFilesValue !== void 0) throw new Error("Use --files or --parent-files, not both");
+      return importImageGenerationOutputs(options.project, {
+        confirmWrite: options.confirmWrite,
+        files: filesValue === void 0 ? void 0 : filesValue.split(",").map((file) => file.trim()).filter(Boolean),
+        jobId: jobId2,
+        manifest: manifestPath === void 0 ? void 0 : readJsonFile(manifestPath, "Generation output manifest"),
+        parentFiles: parentFilesOption(parentFilesValue)
+      });
+    }
+    throw new Error(`Unknown generate image command: ${subcommand}`);
+  }
   if (command === "reroll") {
     const subcommand = positionalArgs(args)[0] || "";
     if (subcommand === "list") {
@@ -5771,6 +6578,15 @@ function printDataResult(command, result, json) {
     if (link.warning) console.log(`Warning: ${link.warning}`);
     return;
   }
+  if (command === "generate" && result && typeof result === "object" && "job" in result) {
+    const generation = result;
+    if (generation.imported) {
+      console.log(`${generation.idempotent ? "Already imported" : "Imported"} ${generation.imported.length} output(s) for ${generation.job?.id || "job"}`);
+    } else {
+      console.log(`Generation job ${generation.job?.id || "job"} ${generation.job?.status || "unknown"}`);
+    }
+    return;
+  }
   if (command === "reroll" && result && typeof result === "object") {
     if ("requests" in result) {
       const listed = result;
@@ -5817,6 +6633,25 @@ function runLineageDbCommand(config, command, args) {
 function runLineageProfileCommand(config, command, args) {
   const runtime = getLineageRuntimeInfo({ channel: config.channel });
   const runtimeIdentity = { channel: config.channel, code: runtime.code, gitSha: runtime.git_sha, version: runtime.version };
+  if (command === "init") {
+    if (hasOption(args, "--db")) throw new Error("Profile init cannot be combined with --db");
+    if (hasOption(args, "--asset-root")) throw new Error("Profile init cannot be combined with --asset-root");
+    if (!args.includes("--confirm-write")) throw new Error("Profile init requires --confirm-write");
+    const profileId = readOption(args, "--profile");
+    if (!profileId) throw new Error("lineage profile init requires --profile");
+    if (process.env.LINEAGE_PROFILE && process.env.LINEAGE_PROFILE !== profileId) {
+      throw new Error("Profile init requires an explicit --profile that does not conflict with LINEAGE_PROFILE");
+    }
+    const serviceOrigin = readOption(args, "--service-origin") || `http://${config.defaultHost}:${config.defaultPort}`;
+    return initializeLineageProfile(profileId, serviceOrigin, runtimeIdentity, true, (profile, initialize) => {
+      const writerLease = acquireProfileWriterLease(profile, config.channel, "cli");
+      try {
+        return initialize();
+      } finally {
+        writerLease.release();
+      }
+    });
+  }
   if (command === "clone") {
     const source = readOption(args, "--source-db");
     const target = readOption(args, "--target-profile");
@@ -5875,7 +6710,10 @@ function printProfileResult(result, json) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (result.schema_version === "lineage.profile_doctor.v1") {
+  if (result.schema_version === "lineage.profile_init.v1") {
+    console.log(`Initialized ${result.profile_id} at ${result.manifest_path}`);
+    console.log(`Service: ${result.service_origin}`);
+  } else if (result.schema_version === "lineage.profile_doctor.v1") {
     console.log(`Profile doctor: ${result.ok ? "ok" : "failed"}`);
     for (const check of result.checks) console.log(`${check.status.toUpperCase()} ${check.id}: ${check.message}`);
   } else if (result.schema_version === "lineage.profile_bind.v1") {
@@ -5916,7 +6754,9 @@ function printRuntimeResult(result, json) {
 }
 function lineageCliRequiresWriterLease(command, args) {
   if (command === "next" || command === "brief" || command === "inspect" || command === "selection") return false;
-  const subcommand = positionalArgs(args)[0] || "";
+  const positions = positionalArgs(args);
+  const subcommand = positions[0] || "";
+  if (command === "generate") return positions[0] !== "image" || positions[1] !== "inspect";
   if (command === "reroll") return subcommand !== "list";
   if (command === "tasks") return subcommand !== "list" && subcommand !== "inspect";
   if (command === "db") return subcommand !== "info";
@@ -6104,7 +6944,6 @@ function start(config, args) {
   } else {
     console.log(`${config.displayName} starting at ${url}`);
     if (options.profile) console.log(`Profile: ${options.profile.profile_id} (${options.profile.environment})`);
-    else console.warn("Warning: legacy-unbound runtime; database and asset paths are not protected by a named profile.");
     console.log(`SQLite: ${options.dbPath}`);
     console.log(`Assets: ${options.assetRoot}`);
   }
@@ -6117,7 +6956,7 @@ function start(config, args) {
       LINEAGE_ASSET_ROOT: options.assetRoot,
       LINEAGE_CHANNEL: config.channel,
       LINEAGE_DB: options.dbPath,
-      LINEAGE_PROFILE: options.profile ? process.env.LINEAGE_PROFILE : void 0,
+      LINEAGE_PROFILE: process.env.LINEAGE_PROFILE,
       LINEAGE_PROFILE_ENVIRONMENT: options.profile?.environment,
       LINEAGE_PROFILE_FINGERPRINT: options.profile?.profile_fingerprint,
       LINEAGE_PROFILE_ID: options.profile?.profile_id,
@@ -6125,7 +6964,7 @@ function start(config, args) {
       LINEAGE_PROFILE_SERVICE_ORIGIN: options.profile?.service_origin,
       LINEAGE_LAUNCHER_PID: String(process.pid),
       LINEAGE_SERVICE_INSTANCE_ID: serviceInstanceId,
-      LINEAGE_DB_ACCESS: options.profile ? void 0 : "read-only",
+      LINEAGE_DB_ACCESS: void 0,
       NODE_ENV: "production",
       PORT: String(options.port)
     },
@@ -6245,7 +7084,7 @@ async function runLineageCli(config, args = process.argv.slice(2)) {
         process.env.LINEAGE_DB_ACCESS = "read-only";
       }
     } else if (requiresWriter) {
-      throw new Error("Persistent writes require --profile; legacy-unbound access is read-only");
+      throw new Error("Persistent writes require --profile; legacy-unbound access is read-only. Create a fresh profile with `profile init --profile <id> --confirm-write`, then pass that profile to the command");
     } else {
       process.env.LINEAGE_DB_ACCESS = "read-only";
     }
@@ -6256,7 +7095,7 @@ async function runLineageCli(config, args = process.argv.slice(2)) {
     else console.error(`${config.binName}: ${message2}`);
     process.exit(1);
   }
-  if (command === "next" || command === "brief" || command === "inspect" || command === "selection" || command === "link-child" || command === "reroll" || command === "tasks") {
+  if (command === "next" || command === "brief" || command === "inspect" || command === "selection" || command === "link-child" || command === "generate" || command === "reroll" || command === "tasks") {
     const commandArgs = normalizedArgs.slice(1);
     const json2 = commandArgs.includes("--json");
     try {