agentlas 0.9.10 → 1.0.2

package/engine/cloud-assets/restore.cjs

@@ -0,0 +1,172 @@
+"use strict";
+/*
+ * cloud-assets/restore — 소유자 Agent Cloud 자산의 나열/복원.
+ *
+ * 계약(약화 금지):
+ *  - list는 서버 검색 결과의 리비전 디스크립터를 로컬 관측 상태로 승격한다.
+ *    (다음 save/delete의 CAS 베이스는 반드시 "관측한" 리비전이어야 한다.)
+ *  - restore 영수증(schema/source/owner/slug/해시/리비전)이 완전히 맞아야만
+ *    로컬 설치를 진행한다. 봉투와 cloudPackage가 어긋나면 invalid_restore_contract.
+ *  - 실제 파일 물질화/DB 반영은 hub/install.cjs persistCloudListing을 재사용한다
+ *    (동일 무결성·crash-recovery 계약, 복제 금지).
+ */
+const {
+  CLOUD_PACKAGE_HASH_V1,
+  cloudPackageHashVersion,
+  normalizeCloudAssetDescriptor,
+  persistCloudListing,
+} = require("../hub/install.cjs");
+const { cargoListAgents, cargoRestorePackage } = require("./cargo.cjs");
+const state = require("./state.cjs");
+
+async function listOwnedCloudAgents(limit = 100) {
+  const result = (await cargoListAgents(limit)) || {
+    schema: "agentlas.agent_cloud.search.v1",
+    source: "cloud",
+    status: "ok",
+    count: 0,
+    total: 0,
+    results: [],
+  };
+  if (!Array.isArray(result.results)) throw new Error("Agent Cloud list returned an invalid results contract.");
+  if (result.results.length) {
+    const stateValue = state.readCloudAssetState();
+    for (const raw of result.results) {
+      const descriptor = normalizeCloudAssetDescriptor(raw, "Agent Cloud list result");
+      const key = state.cloudDescriptorKey(descriptor);
+      const previous = stateValue.assets[key];
+      const preserveRoots = previous && previous.descriptor.cloudId === descriptor.cloudId && previous.descriptor.revision === descriptor.revision;
+      stateValue.assets[key] = { descriptor, sourceRoots: preserveRoots ? previous.sourceRoots : [] };
+    }
+    state.writeCloudAssetState(stateValue);
+  }
+  return result;
+}
+
+function normalizeOwnerRestorePayload(raw, expectedSlug) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid_restore_contract");
+  if (raw.schema !== "agentlas.agent_cloud.restore.v1" || raw.source !== "cloud" || raw.owner !== true) {
+    throw new Error("invalid_restore_contract");
+  }
+  if (typeof raw.slug !== "string" || !raw.slug || raw.slug !== expectedSlug) {
+    // cross-slug 응답을 그대로 설치하면 다른 자산이 요청 슬러그로 위장 설치된다.
+    throw new Error(`restore_slug_mismatch: requested ${expectedSlug}; received ${String(raw.slug || "")}`);
+  }
+  const pkg = raw.cloudPackage;
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg) || !Array.isArray(pkg.files)) {
+    throw new Error("invalid_restore_contract");
+  }
+  const version = cloudPackageHashVersion(pkg.packageHashVersion);
+  if (!version || !/^[a-f0-9]{64}$/i.test(String(pkg.packageHash || "").replace(/^sha256:/i, ""))) {
+    throw new Error("invalid_restore_contract");
+  }
+  let descriptor;
+  let nestedDescriptor;
+  try {
+    descriptor = normalizeCloudAssetDescriptor(raw, "owner restore receipt");
+    nestedDescriptor = normalizeCloudAssetDescriptor({
+      ...pkg,
+      slug: raw.slug,
+      etag: raw.etag,
+    }, "owner restore package receipt");
+  } catch (error) {
+    throw new Error(`invalid_restore_contract: ${error.message || error}`);
+  }
+  if (JSON.stringify(descriptor) !== JSON.stringify(nestedDescriptor)) {
+    throw new Error("invalid_restore_contract: restore revision envelope and cloudPackage disagree");
+  }
+  if (!["agent", "team", "repo"].includes(pkg.agentKind) || !Number.isSafeInteger(pkg.fileCount) || !Number.isSafeInteger(pkg.totalBytes)) {
+    throw new Error("invalid_restore_contract");
+  }
+  for (const file of pkg.files) {
+    if (!file || typeof file !== "object" || typeof file.path !== "string" || !Number.isSafeInteger(file.bytes) || typeof file.sha256 !== "string" || typeof file.contentBase64 !== "string") {
+      throw new Error("invalid_restore_contract");
+    }
+  }
+  const outerVersion = raw.packageHashVersion == null ? version : cloudPackageHashVersion(raw.packageHashVersion);
+  if (
+    (raw.packageHash != null && String(raw.packageHash) !== String(pkg.packageHash)) ||
+    !outerVersion || outerVersion !== version ||
+    (raw.fileCount != null && raw.fileCount !== pkg.fileCount) ||
+    (raw.totalBytes != null && raw.totalBytes !== pkg.totalBytes) ||
+    (raw.agentKind != null && raw.agentKind !== pkg.agentKind)
+  ) {
+    throw new Error("invalid_restore_contract: restore envelope and cloudPackage disagree");
+  }
+  return {
+    schema: raw.schema,
+    source: raw.source,
+    owner: true,
+    slug: raw.slug,
+    name: typeof raw.name === "string" && raw.name ? raw.name : raw.slug,
+    nameEn: typeof raw.nameEn === "string" && raw.nameEn ? raw.nameEn : (raw.name || raw.slug),
+    tagline: typeof raw.tagline === "string" ? raw.tagline : "",
+    taglineEn: typeof raw.taglineEn === "string" ? raw.taglineEn : (raw.tagline || ""),
+    descriptor,
+    cloudPackage: {
+      cloudId: descriptor.cloudId,
+      scope: descriptor.scope,
+      revision: descriptor.revision,
+      updatedAt: descriptor.updatedAt,
+      packageHash: String(pkg.packageHash).replace(/^sha256:/i, "").toLowerCase(),
+      packageHashVersion: version,
+      fileCount: pkg.fileCount,
+      totalBytes: pkg.totalBytes,
+      agentKind: pkg.agentKind,
+      runtimeLabels: Array.isArray(pkg.runtimeLabels) ? pkg.runtimeLabels.filter((item) => typeof item === "string" && item.trim()) : [],
+      files: pkg.files,
+    },
+  };
+}
+
+async function restoreOwnedCloudAgent(db, slug) {
+  const raw = await cargoRestorePackage(slug);
+  if (!raw || raw.error) {
+    const code = raw && raw.error ? raw.error : "agent_not_found";
+    const message = raw && raw.message ? raw.message : `Agent Cloud package not found: ${slug}`;
+    throw new Error(`${code}: ${message}`);
+  }
+  const restored = normalizeOwnerRestorePayload(raw, slug);
+  const cloudPackage = restored.cloudPackage;
+  const listing = {
+    slug: restored.slug || slug,
+    name: restored.name || restored.nameEn || restored.slug || slug,
+    nameEn: restored.nameEn || restored.name || restored.slug || slug,
+    tagline: restored.tagline || restored.taglineEn || "",
+    taglineEn: restored.taglineEn || restored.tagline || "",
+    trustGrade: "A",
+    visibility: "visible",
+    source: "cloud",
+    assetDescriptor: restored.descriptor,
+    cloudPackage,
+  };
+  const agent = persistCloudListing(db, listing);
+  let descriptor = restored.descriptor;
+  let localStateWarning;
+  try {
+    descriptor = state.rememberCloudAssetDescriptor(restored.descriptor, { sourceRoot: agent.localPath || undefined });
+  } catch (error) {
+    localStateWarning = `Restore completed, but observed revision state could not be indexed: ${error.message || error}`;
+  }
+  return {
+    schema: restored.schema || "agentlas.agent_cloud.restore.v1",
+    source: "cloud",
+    slug: agent.slug,
+    name: agent.name,
+    packageHash: cloudPackage.packageHash,
+    packageHashVersion: cloudPackage.packageHashVersion || CLOUD_PACKAGE_HASH_V1,
+    cloudId: descriptor.cloudId,
+    scope: descriptor.scope,
+    revision: descriptor.revision,
+    etag: descriptor.etag,
+    updatedAt: descriptor.updatedAt,
+    localPath: agent.localPath || null,
+    ...(localStateWarning ? { localStateWarning } : {}),
+  };
+}
+
+module.exports = {
+  listOwnedCloudAgents,
+  normalizeOwnerRestorePayload,
+  restoreOwnedCloudAgent,
+};

package/engine/cloud-assets/state.cjs

@@ -0,0 +1,268 @@
+"use strict";
+/*
+ * cloud-assets/state — Agent Cloud 자산 리비전의 로컬 관측 상태.
+ *
+ * 두 저장소를 관리한다 (v1 monolith의 asset-state 계열 충실 이식):
+ *  1. <userData>/cloud-asset-state.v1.json — 이 머신이 "관측한" 각 자산의
+ *     마지막 리비전 디스크립터 + 소스 루트 목록 + 삭제 톰스톤(deletedBases).
+ *  2. <sourceRoot>/.agentlas-cloud-package.json — 소스 폴더 마커. scope별
+ *     디스크립터(cloudAssets)를 담아 다음 save의 CAS 베이스가 된다.
+ *
+ * 계약(약화 금지):
+ *  - 관측한 베이스 리비전 없이는 어떤 덮어쓰기도 시도하지 않는다. 이 파일이
+ *    깨졌으면 조용히 새로 만들지 않고 정직하게 실패한다 (조용한 기본값 금지).
+ *  - 삭제 톰스톤: delete가 커밋된 (rootPath, slug, scope, cloudId, revision)은
+ *    다시 베이스로 채택되지 않는다 — delete→재저장은 반드시 새 생성(If-None-Match)이다.
+ *  - 상태 파일 쓰기는 O_EXCL temp → fsync → rename → dir fsync (크래시 원자성).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { userDataDir } = require("../core/paths.cjs");
+const {
+  CLOUD_ASSET_SCOPES,
+  CLOUD_PACKAGE_HASH_V1,
+  CLOUD_RESTORE_MARKER_PATH,
+  cloudSlug,
+  cloudApplyPortableFileMode,
+  cloudFsyncDirectory,
+  normalizeCloudAssetDescriptor,
+} = require("../hub/install.cjs");
+
+const CLOUD_ASSET_STATE_FILE = "cloud-asset-state.v1.json";
+
+function normalizeCloudScopeFlag(value) {
+  if (value === "owner-private" || value === "private" || value === "private-link") return "owner-private";
+  if (value === "hub-public" || value === "marketplace" || value === "public") return "hub-public";
+  return null;
+}
+
+function cloudDescriptorKey(descriptor) {
+  return `${descriptor.scope}:${descriptor.slug}`;
+}
+
+function cloudAssetStatePath() {
+  return path.join(userDataDir(), CLOUD_ASSET_STATE_FILE);
+}
+
+function readCloudAssetState() {
+  const statePath = cloudAssetStatePath();
+  if (!fs.existsSync(statePath)) return { schemaVersion: 1, assets: {}, deletedBases: [] };
+  let fd;
+  try {
+    // O_NOFOLLOW: 상태 파일이 심링크로 바꿔치기되면 읽지 않는다 (로컬 상태 위조 방어).
+    fd = fs.openSync(statePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("state file is not a bounded regular file");
+    const parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
+    if (!parsed || parsed.schemaVersion !== 1 || !parsed.assets || typeof parsed.assets !== "object" || Array.isArray(parsed.assets)) {
+      throw new Error("state schema is invalid");
+    }
+    const assets = {};
+    for (const [key, raw] of Object.entries(parsed.assets)) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`state entry ${key} is invalid`);
+      const descriptor = normalizeCloudAssetDescriptor(raw.descriptor, `state entry ${key}`);
+      if (key !== cloudDescriptorKey(descriptor)) throw new Error(`state entry ${key} key is invalid`);
+      const sourceRoots = Array.isArray(raw.sourceRoots)
+        ? [...new Set(raw.sourceRoots.filter((item) => typeof item === "string" && path.isAbsolute(item)).map((item) => path.resolve(item)))].slice(0, 32)
+        : [];
+      assets[key] = { descriptor, sourceRoots };
+    }
+    const deletedBases = Array.isArray(parsed.deletedBases)
+      ? parsed.deletedBases.filter((item) =>
+          item && typeof item === "object" && !Array.isArray(item) &&
+          typeof item.rootPath === "string" && path.isAbsolute(item.rootPath) &&
+          typeof item.slug === "string" && cloudSlug(item.slug) === item.slug &&
+          CLOUD_ASSET_SCOPES.has(item.scope) && typeof item.cloudId === "string" &&
+          typeof item.revision === "string"
+        ).map((item) => ({
+          rootPath: path.resolve(item.rootPath),
+          slug: item.slug,
+          scope: item.scope,
+          cloudId: item.cloudId,
+          revision: item.revision,
+        })).slice(-256)
+      : [];
+    return { schemaVersion: 1, assets, deletedBases };
+  } catch (error) {
+    // 깨진 상태 파일을 빈 상태로 위장하면 stale 베이스로 원격 리비전을 덮어쓸 수 있다.
+    throw new Error(`Agent Cloud local revision state is unreadable: ${error.message || error}`);
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
+function writeCloudAssetState(state) {
+  const statePath = cloudAssetStatePath();
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  const temp = `${statePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  const fd = fs.openSync(temp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(state, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temp, statePath);
+  cloudApplyPortableFileMode(statePath, 0o600);
+  cloudFsyncDirectory(path.dirname(statePath));
+}
+
+/** 서버가 준 리비전 영수증을 관측 상태로 승격. sourceRoot가 있으면 톰스톤도 해제한다. */
+function rememberCloudAssetDescriptor(value, options = {}) {
+  const descriptor = normalizeCloudAssetDescriptor(value);
+  const state = readCloudAssetState();
+  const key = cloudDescriptorKey(descriptor);
+  const previous = state.assets[key];
+  const sameRevision = previous && previous.descriptor.cloudId === descriptor.cloudId && previous.descriptor.revision === descriptor.revision;
+  const roots = sameRevision ? [...previous.sourceRoots] : [];
+  if (options.sourceRoot) {
+    const sourceRoot = path.resolve(options.sourceRoot);
+    roots.push(sourceRoot);
+    state.deletedBases = state.deletedBases.filter(
+      (item) => !(item.rootPath === sourceRoot && item.slug === descriptor.slug && item.scope === descriptor.scope),
+    );
+  }
+  state.assets[key] = { descriptor, sourceRoots: [...new Set(roots)].slice(0, 32) };
+  writeCloudAssetState(state);
+  return descriptor;
+}
+
+function findCloudAssetDescriptor(slug, scope) {
+  const safeSlug = cloudSlug(slug);
+  const state = readCloudAssetState();
+  const matches = Object.values(state.assets).filter(
+    (entry) => entry.descriptor.slug === safeSlug && (!scope || entry.descriptor.scope === scope),
+  );
+  if (!scope && matches.length > 1) {
+    // 같은 슬러그가 두 scope에 있으면 "아무거나" 지우지 않는다 — 정확한 지정 강제.
+    throw new Error(`Cloud asset ${safeSlug} exists in multiple scopes. Retry with --scope owner-private or --scope hub-public.`);
+  }
+  return matches.length === 1 ? matches[0] : null;
+}
+
+// ── 소스 폴더 마커 (.agentlas-cloud-package.json) ──
+
+function cloudMarkerDescriptors(marker) {
+  const descriptors = {};
+  if (!marker || typeof marker !== "object" || Array.isArray(marker)) return descriptors;
+  if (marker.cloudAssets && typeof marker.cloudAssets === "object" && !Array.isArray(marker.cloudAssets)) {
+    for (const scope of CLOUD_ASSET_SCOPES) {
+      if (!marker.cloudAssets[scope]) continue;
+      try {
+        const descriptor = normalizeCloudAssetDescriptor(marker.cloudAssets[scope], `local marker ${scope}`);
+        if (descriptor.scope === scope) descriptors[scope] = descriptor;
+      } catch { /* 레거시/손상 CAS 항목은 베이스 리비전으로 채택하지 않는다 */ }
+    }
+  }
+  if (marker.revision && marker.cloudId && marker.scope) {
+    try {
+      const descriptor = normalizeCloudAssetDescriptor(marker, "local marker");
+      if (!descriptors[descriptor.scope]) descriptors[descriptor.scope] = descriptor;
+    } catch { /* legacy marker */ }
+  }
+  return descriptors;
+}
+
+function cloudBaseDescriptorFromMarker(marker, slug, scope) {
+  const descriptor = cloudMarkerDescriptors(marker)[scope];
+  return descriptor && descriptor.slug === slug ? descriptor : null;
+}
+
+/**
+ * 다음 save의 CAS 베이스 결정: 마커 vs 상태 저널.
+ * 톰스톤에 걸린 마커 디스크립터는 무시(삭제 후 재저장은 새 생성이어야 한다).
+ * 둘 다 있으면 같은 cloudId에서 더 최신 관측을 채택한다.
+ */
+function cloudBaseDescriptorForSource(marker, rootPath, slug, scope) {
+  const state = readCloudAssetState();
+  const normalizedRoot = path.resolve(rootPath);
+  let markerDescriptor = cloudBaseDescriptorFromMarker(marker, slug, scope);
+  if (markerDescriptor && state.deletedBases.some((item) =>
+    item.rootPath === normalizedRoot && item.slug === slug && item.scope === scope &&
+    item.cloudId === markerDescriptor.cloudId && item.revision === markerDescriptor.revision
+  )) {
+    markerDescriptor = null;
+  }
+  const entry = state.assets[`${scope}:${slug}`];
+  const stateDescriptor = entry && entry.sourceRoots.includes(normalizedRoot) ? entry.descriptor : null;
+  if (!markerDescriptor) return stateDescriptor;
+  if (!stateDescriptor) return markerDescriptor;
+  return stateDescriptor.cloudId === markerDescriptor.cloudId && stateDescriptor.updatedAt >= markerDescriptor.updatedAt
+    ? stateDescriptor
+    : markerDescriptor;
+}
+
+function writeCloudSourceMarker(rootPath, scan, descriptor, options = {}) {
+  const markerPath = path.join(rootPath, CLOUD_RESTORE_MARKER_PATH);
+  if (fs.existsSync(markerPath)) {
+    const stat = fs.lstatSync(markerPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Agent Cloud revision marker is not a regular file");
+  }
+  const descriptors = cloudMarkerDescriptors(options.previousMarker);
+  if (descriptor) descriptors[descriptor.scope] = descriptor;
+  if (options.removeDescriptor) {
+    const current = descriptors[options.removeDescriptor.scope];
+    if (current && current.cloudId === options.removeDescriptor.cloudId && current.revision === options.removeDescriptor.revision) {
+      delete descriptors[options.removeDescriptor.scope];
+    }
+  }
+  const latest = descriptor || Object.values(descriptors)[0] || null;
+  const marker = {
+    schemaVersion: 1,
+    source: "agentlas-cloud",
+    slug: latest?.slug || options.removeDescriptor?.slug || cloudSlug(path.basename(rootPath)),
+    packageHash: descriptor?.packageHash || options.packageHash || options.previousMarker?.packageHash || "",
+    packageHashVersion: descriptor?.packageHashVersion || options.packageHashVersion || options.previousMarker?.packageHashVersion || CLOUD_PACKAGE_HASH_V1,
+    fileCount: Number.isSafeInteger(options.fileCount) ? options.fileCount : (options.previousMarker?.fileCount || 0),
+    totalBytes: Number.isSafeInteger(options.totalBytes) ? options.totalBytes : (options.previousMarker?.totalBytes || 0),
+    executablePaths: Array.isArray(options.executablePaths) ? options.executablePaths : options.previousMarker?.executablePaths,
+    cloudAssets: descriptors,
+    ...(latest ? latest : {}),
+    restoredAt: options.previousMarker?.restoredAt,
+    savedAt: new Date().toISOString(),
+  };
+  for (const key of Object.keys(marker)) if (marker[key] === undefined) delete marker[key];
+  const temp = path.join(rootPath, `.${CLOUD_RESTORE_MARKER_PATH}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+  const fd = fs.openSync(temp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(marker, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temp, markerPath);
+  cloudApplyPortableFileMode(markerPath, 0o600);
+  cloudFsyncDirectory(rootPath);
+  return marker;
+}
+
+function readCloudSourceMarker(rootPath) {
+  const markerPath = path.join(rootPath, CLOUD_RESTORE_MARKER_PATH);
+  if (!fs.existsSync(markerPath)) return null;
+  let fd;
+  try {
+    fd = fs.openSync(markerPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("marker is not a bounded regular file");
+    return JSON.parse(fs.readFileSync(fd, "utf8"));
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+module.exports = {
+  CLOUD_ASSET_STATE_FILE,
+  normalizeCloudScopeFlag,
+  cloudDescriptorKey,
+  cloudAssetStatePath,
+  readCloudAssetState,
+  writeCloudAssetState,
+  rememberCloudAssetDescriptor,
+  findCloudAssetDescriptor,
+  cloudMarkerDescriptors,
+  cloudBaseDescriptorFromMarker,
+  cloudBaseDescriptorForSource,
+  writeCloudSourceMarker,
+  readCloudSourceMarker,
+};

package/engine/commands/automation.cjs

@@ -0,0 +1,195 @@
+"use strict";
+/*
+ * automation — 자동화 등록/목록/토글/삭제/실행 (v1 cmdAutomation 의 v2 포팅).
+ *   list (기본) | add | on <id> | off <id> | remove <id> | run <id> | runs | daemon
+ *
+ * 스케줄 계산은 automation/schedule, DB는 automation/store, 실행은
+ * automation/daemon(세션 계층)만 쓴다. run <id> 는 스케줄을 건드리지 않는다
+ * (앱의 advanceSchedule=false 와 동일); 예약 전진은 daemon 경로에서만 일어난다.
+ */
+const { findAgent } = require("../agents/registry.cjs");
+const schedule = require("../automation/schedule.cjs");
+const store = require("../automation/store.cjs");
+const daemon = require("../automation/daemon.cjs");
+
+function resolveFirm(db, token) {
+  const q = String(token || "").trim();
+  if (!q) return null;
+  try {
+    return db.prepare("SELECT * FROM firms WHERE id = ? OR lower(slug) = lower(?) OR name = ?").get(q, q, q) || null;
+  } catch {
+    return null;
+  }
+}
+
+async function run(ctx, args) {
+  const sub = args[0] || "list";
+  const ko = ctx.lang === "ko";
+  const db = ctx.db();
+  const usage = (tail) => (ko ? `사용법: agentlas automation ${tail}` : `usage: agentlas automation ${tail}`);
+  const missingAutomation = (id) => (ko ? `자동화를 찾지 못했습니다: ${id}` : `Automation not found: ${id}`);
+  const fail = (msg) => { ctx.err(msg); return 1; };
+
+  if (sub === "list") {
+    const rows = store.listAutomations(db);
+    if (!rows.length) {
+      ctx.out(ko
+        ? "자동화가 없습니다. `agentlas automation add --help`로 추가 방법을 확인하세요."
+        : "No automations. Run agentlas automation add --help.");
+      return 0;
+    }
+    for (const r of rows) {
+      const target = r.target_type + ":" + String(r.target_id).slice(0, 24);
+      ctx.out(
+        `${r.enabled ? ctx.ui.green("●") : ctx.ui.dim("○")} ${ctx.ui.bold(String(r.id).slice(0, 8))}  ${String(r.name).padEnd(28).slice(0, 28)} ` +
+          `${String(r.schedule || r.trigger_type || "-").padEnd(14)} ${target.padEnd(32)} ` +
+          `${ko ? "다음" : "next"}=${r.next_run_at ? r.next_run_at.slice(0, 16) : "-"} ` +
+          `${ko ? "성공" : "success"}=${r.run_count ?? 0}`,
+      );
+    }
+    ctx.out("");
+    ctx.out(ctx.ui.dim(ko
+      ? "지금 실행: agentlas automation run <id>  ·  데몬: agentlas automation daemon"
+      : "Run now: agentlas automation run <id>  ·  daemon: agentlas automation daemon"));
+    ctx.out(ctx.ui.dim(ko
+      ? "Desktop 앱이 열려 있을 때는 Desktop 스케줄러도 실행되며, 리스로 중복 실행을 막습니다."
+      : "The Desktop scheduler also runs when the app is open; leases prevent duplicate runs."));
+    return 0;
+  }
+
+  if (sub === "add") {
+    // agentlas automation add --name "..." --agent <slug>|--firm <slug> --cron "0 9 * * *" --prompt "..."
+    const flags = {};
+    for (let i = 1; i < args.length; i++) {
+      const a = args[i];
+      if (a === "--name") flags.name = args[++i];
+      else if (a === "--agent") flags.agent = args[++i];
+      else if (a === "--firm") flags.firm = args[++i];
+      else if (a === "--cron") flags.cron = args[++i];
+      else if (a === "--prompt") flags.prompt = args[++i];
+      else if (a === "--tz") flags.tz = args[++i];
+      else if (a === "--disabled") flags.disabled = true;
+    }
+    if (!flags.cron || !flags.prompt || (!flags.agent && !flags.firm)) {
+      ctx.err(ko
+        ? '사용법: agentlas automation add --name "이름" --agent <슬러그>|--firm <슬러그> --cron "0 9 * * *" --prompt "지시" [--tz Asia/Seoul] [--disabled]'
+        : 'usage: agentlas automation add --name "name" --agent <slug>|--firm <slug> --cron "0 9 * * *" --prompt "instructions" [--tz Asia/Seoul] [--disabled]');
+      return 1;
+    }
+    let targetType;
+    let targetId;
+    let targetLabel;
+    if (flags.agent) {
+      const a = findAgent(db, flags.agent);
+      if (!a) return fail(ko ? `에이전트를 찾지 못했습니다: ${flags.agent}` : `Agent not found: ${flags.agent}`);
+      targetType = "agent";
+      targetId = a.id;
+      targetLabel = a.name;
+    } else {
+      const f = resolveFirm(db, flags.firm);
+      if (!f) return fail(ko ? `회사를 찾지 못했습니다: ${flags.firm}` : `Company not found: ${flags.firm}`);
+      targetType = "firm";
+      targetId = f.id;
+      targetLabel = f.name;
+    }
+    const next = schedule.nextCronRun(flags.cron, new Date(), flags.tz || null);
+    if (!next) {
+      return fail(ko
+        ? `cron 표현식을 해석하지 못했습니다: "${flags.cron}" (5개 필드: 분 시 일 월 요일)`
+        : `Could not parse cron expression: "${flags.cron}" (5 fields: minute hour day month weekday)`);
+    }
+    const id = store.addAutomation(db, {
+      name: flags.name || `${targetLabel} automation`,
+      targetType,
+      targetId,
+      cron: flags.cron,
+      prompt: flags.prompt,
+      tz: flags.tz || null,
+      disabled: !!flags.disabled,
+    }, next);
+    ctx.out(`${ko ? "생성됨" : "Created"}: ${ctx.ui.bold(id.slice(0, 8))}  ${flags.name || targetLabel}  ${ko ? "다음" : "next"}=${next.toISOString().slice(0, 16)}`);
+    ctx.out(ctx.ui.dim(ko
+      ? `지금 실행: agentlas automation run ${id.slice(0, 8)}  ·  예약 실행: agentlas automation daemon (또는 Desktop)`
+      : `Run now: agentlas automation run ${id.slice(0, 8)}  ·  scheduled: agentlas automation daemon (or Desktop)`));
+    return 0;
+  }
+
+  if (sub === "on" || sub === "off") {
+    const idPrefix = args[1];
+    if (!idPrefix) return fail(usage(`${sub} <id>`));
+    const row = store.getAutomationByPrefix(db, idPrefix);
+    if (!row) return fail(missingAutomation(idPrefix));
+    store.setEnabled(db, row, sub === "on");
+    ctx.out(`${sub === "on" ? (ko ? "활성화됨" : "Enabled") : (ko ? "비활성화됨" : "Disabled")}: ${row.id.slice(0, 8)}  ${row.name}`);
+    return 0;
+  }
+
+  if (sub === "remove" || sub === "rm") {
+    const idPrefix = args[1];
+    if (!idPrefix) return fail(usage("remove <id>"));
+    const row = store.getAutomationByPrefix(db, idPrefix);
+    if (!row) return fail(missingAutomation(idPrefix));
+    store.removeAutomation(db, row.id);
+    ctx.out(`${ko ? "삭제됨" : "Deleted"}: ${row.id.slice(0, 8)}  ${row.name}`);
+    return 0;
+  }
+
+  if (sub === "runs") {
+    const rows = store.listRuns(db, 15);
+    if (!rows.length) {
+      ctx.out(ko ? "실행 기록이 없습니다." : "No run history.");
+      return 0;
+    }
+    for (const r of rows) {
+      const status = ko
+        ? (r.status === "ok" ? "성공" : r.status === "error" ? "오류" : (r.status || "?"))
+        : (r.status || "?");
+      ctx.out(
+        `${(r.ran_at || "").slice(0, 16).padEnd(17)} ${(r.status === "ok" ? ctx.ui.green(status.padEnd(9)) : ctx.ui.red(status.padEnd(9)))} ` +
+          `${(r.name || (ko ? "(삭제됨)" : "(deleted)")).slice(0, 30).padEnd(31)} ${r.error ? ctx.ui.dim(String(r.error).slice(0, 40)) : ""}`,
+      );
+    }
+    return 0;
+  }
+
+  if (sub === "run") {
+    const idPrefix = args[1];
+    let runtimeOverride = null;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === "--runtime") runtimeOverride = args[++i];
+    }
+    if (!idPrefix) return fail(usage("run <id>"));
+    const row = store.getAutomationByPrefix(db, idPrefix);
+    if (!row) return fail(missingAutomation(idPrefix));
+    // run-now는 스케줄을 건드리지 않는다 (앱의 advanceSchedule=false와 동일).
+    let renderer = null;
+    const r = await daemon.runAutomationOnce(ctx, db, row, {
+      advanceSchedule: false,
+      runtimeOverride,
+      onSession: (session) => {
+        if (ctx.uiInstance) {
+          const { Renderer } = require("../ui/renderer.cjs");
+          renderer = new Renderer(ctx.uiInstance);
+          renderer.attach(session, { replay: false });
+        }
+      },
+    });
+    if (renderer) renderer.detach();
+    return r.ok ? 0 : 1;
+  }
+
+  if (sub === "daemon") {
+    let interval = 30;
+    let runtimeOverride = null;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--interval") interval = Math.max(10, Number(args[++i]) || 30);
+      else if (args[i] === "--runtime") runtimeOverride = args[++i];
+    }
+    return daemon.automationDaemon(ctx, db, { intervalSec: interval, runtimeOverride });
+  }
+
+  ctx.err(usage("list|add|on <id>|off <id>|remove <id>|run <id>|runs|daemon"));
+  return 1;
+}
+
+module.exports = { run };