@trycadence/cli 0.1.1 → 0.1.3

package/dist/cadence

@@ -1447,7 +1447,16 @@ function createCadenceClient(options = {}) {
     rpc,
     health: () => getCadenceHealth(healthOptions),
     auth: {
-      login: (input) => rpc.auth.login.mutate(input)
+      login: (input) => rpc.auth.login.mutate(input),
+      cli: {
+        start: (input) => rpc.auth.cli.start.mutate(input),
+        poll: (input) => rpc.auth.cli.poll.query(input),
+        complete: (input) => rpc.auth.cli.complete.mutate(input),
+        refresh: (input) => rpc.auth.cli.refresh.mutate(input)
+      }
+    },
+    actors: {
+      ensureWorkspaceAgent: (input) => rpc.actors.ensureWorkspaceAgent.mutate(input)
     },
     events: {
       list: (input) => rpc.events.list.query(input)
@@ -1462,7 +1471,8 @@ function createCadenceClient(options = {}) {
       attach: (input) => rpc.tickets.attach.mutate(input),
       update: (input) => rpc.tickets.update.mutate(input),
       changeStatus: (input) => rpc.tickets.changeStatus.mutate(input),
-      complete: (input) => rpc.tickets.complete.mutate(input)
+      complete: (input) => rpc.tickets.complete.mutate(input),
+      log: (input) => rpc.tickets.log.mutate(input)
     },
     intake: {
       create: (input) => rpc.intake.create.mutate(input),
@@ -1471,6 +1481,7 @@ function createCadenceClient(options = {}) {
     sessions: {
       start: (input) => rpc.sessions.start.mutate(input),
       end: (input) => rpc.sessions.end.mutate(input),
+      files: (input) => rpc.sessions.files.mutate(input),
       current: (input) => rpc.sessions.current.query(input),
       leases: {
         create: (input) => rpc.sessions.leases.create.mutate(input),
@@ -1480,20 +1491,41 @@ function createCadenceClient(options = {}) {
     changesets: {
       create: (input) => rpc.changesets.create.mutate(input),
       get: (input) => rpc.changesets.get.query(input),
-      list: (input) => rpc.changesets.list.query(input)
+      context: (input) => rpc.changesets.context.query(input),
+      list: (input) => rpc.changesets.list.query(input),
+      notes: {
+        get: (input) => rpc.changesets.notes.get.query(input),
+        put: (input) => rpc.changesets.notes.put.mutate(input),
+        apply: (input) => rpc.changesets.notes.markApplied.mutate(input)
+      }
+    },
+    projects: {
+      default: () => rpc.projects.default.query(),
+      list: () => rpc.projects.list.query(),
+      resolve: (input) => rpc.projects.resolve.query(input)
     }
   };
 }
 
 // src/index.ts
 import { spawnSync } from "child_process";
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, join, parse } from "path";
+import { createHash, randomUUID } from "crypto";
+import { mkdir, readFile, rm, stat, writeFile } from "fs/promises";
+import { basename, dirname, isAbsolute, join, parse } from "path";
 import { createInterface } from "readline/promises";
 var ticketPriorities = ["low", "normal", "high", "urgent"];
 var ticketStatuses = ["backlog", "ready", "in_progress", "blocked", "review", "done", "abandoned"];
+var sessionFileChangeKinds = ["added", "modified", "deleted", "renamed", "unknown"];
+var workLogEntryKinds = ["intent", "decision", "rationale", "action", "verification", "blocker", "correction", "note"];
+var workLogParentSelectors = ["last", "ticket-last", "session-last", "last-decision", "last-correction", "last-action"];
+var changesetPrNoteSources = ["agent", "human", "system"];
 var defaultLeaseTtlSeconds = 5 * 60 * 60;
 var defaultCliApiBaseUrl = "https://cadenceapi.deploy.lvl8studios.com";
+var defaultCliWebBaseUrl = "https://cadence.deploy.lvl8studios.com";
+var credentialRefreshSkewMs = 60 * 1000;
+var credentialRefreshLockTimeoutMs = 10 * 1000;
+var credentialRefreshLockStaleMs = 60 * 1000;
+var credentialRefreshLockPollMs = 100;
 
 class CliError extends Error {
   code;
@@ -1513,14 +1545,20 @@ function readFlagValue(argv, index, flag) {
   return value;
 }
 var knownCommandPaths = [
+  ["actors", "ensure-workspace-agent"],
   ["auth", "login"],
   ["auth", "status"],
   ["auth", "logout"],
   ["changesets", "create"],
   ["changesets", "list"],
   ["changesets", "get"],
+  ["changesets", "current"],
+  ["changesets", "notes", "get"],
+  ["changesets", "notes", "put"],
+  ["changesets", "notes", "apply"],
   ["sessions", "start"],
   ["sessions", "end"],
+  ["sessions", "files"],
   ["sessions", "current"],
   ["intake", "dismiss"],
   ["intake"],
@@ -1528,12 +1566,14 @@ var knownCommandPaths = [
   ["tickets", "complete"],
   ["tickets", "release"],
   ["tickets", "claim"],
+  ["tickets", "log"],
   ["tickets", "update"],
   ["tickets", "create"],
   ["tickets", "list"],
   ["tickets", "get"],
   ["events", "list"],
   ["work", "overview"],
+  ["projects", "list"],
   ["init"],
   ["status"],
   ["help"]
@@ -1591,7 +1631,10 @@ function parseCliArgs(argv) {
       continue;
     }
     if (arg.startsWith("--")) {
-      options[arg.slice(2)] = readFlagValue(argv, index, arg);
+      const key = arg.slice(2);
+      const value = readFlagValue(argv, index, arg);
+      options[key] = key === "file" && options[key] ? `${options[key]}
+${value}` : value;
       index += 1;
       continue;
     }
@@ -1620,12 +1663,40 @@ function safeJsonParse(source, filePath) {
   }
   const record = parsed;
   const server = typeof record.server === "string" ? record.server : undefined;
+  const webBaseUrl = typeof record.webBaseUrl === "string" ? record.webBaseUrl : undefined;
+  const profile = typeof record.profile === "string" ? record.profile : undefined;
   const projectId = typeof record.projectId === "string" ? record.projectId : typeof record.project === "string" ? record.project : undefined;
+  const profiles = parseProfiles(record.profiles, filePath);
   return {
     ...server ? { server } : {},
-    ...projectId ? { projectId } : {}
+    ...webBaseUrl ? { webBaseUrl } : {},
+    ...projectId ? { projectId } : {},
+    ...profile ? { profile } : {},
+    ...profiles ? { profiles } : {}
   };
 }
+function parseProfiles(value, filePath) {
+  if (value === undefined) {
+    return;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliError("CONFIG_ERROR", `${filePath} profiles must be a JSON object.`);
+  }
+  const profiles = {};
+  for (const [name, rawProfile] of Object.entries(value)) {
+    if (!rawProfile || typeof rawProfile !== "object" || Array.isArray(rawProfile)) {
+      throw new CliError("CONFIG_ERROR", `${filePath} profile '${name}' must be a JSON object.`);
+    }
+    const profileRecord = rawProfile;
+    const server = typeof profileRecord.server === "string" ? profileRecord.server : undefined;
+    const webBaseUrl = typeof profileRecord.webBaseUrl === "string" ? profileRecord.webBaseUrl : undefined;
+    profiles[name] = {
+      ...server ? { server } : {},
+      ...webBaseUrl ? { webBaseUrl } : {}
+    };
+  }
+  return profiles;
+}
 async function readOptionalConfig(filePath) {
   const file = Bun.file(filePath);
   if (!await file.exists()) {
@@ -1645,12 +1716,104 @@ async function mergeConfigFile(filePath, updates) {
     ...updates
   });
 }
-async function findRepoConfigPath(cwd) {
+function parseAgentIdentityCache(source, filePath) {
+  const parsed = JSON.parse(source);
+  if (!parsed || typeof parsed !== "object") {
+    throw new CliError("CONFIG_ERROR", `${filePath} must contain a JSON object.`);
+  }
+  const record = parsed;
+  const identities = record.identities;
+  if (record.version !== 1 || typeof record.workspaceRef !== "string" || typeof record.workspaceName !== "string" || !identities || typeof identities !== "object" || Array.isArray(identities)) {
+    throw new CliError("CONFIG_ERROR", `${filePath} is not a valid Cadence agent identity cache.`);
+  }
+  const normalizedIdentities = {};
+  for (const [key, value] of Object.entries(identities)) {
+    if (!value || typeof value !== "object") {
+      throw new CliError("CONFIG_ERROR", `${filePath} contains an invalid identity entry.`);
+    }
+    const identity2 = value;
+    if (typeof identity2.actorId !== "string" || typeof identity2.displayName !== "string" || identity2.kind !== "agent" || typeof identity2.agentKind !== "string" || typeof identity2.updatedAt !== "string") {
+      throw new CliError("CONFIG_ERROR", `${filePath} contains an invalid identity entry.`);
+    }
+    normalizedIdentities[key] = {
+      actorId: identity2.actorId,
+      displayName: identity2.displayName,
+      kind: "agent",
+      agentKind: identity2.agentKind,
+      updatedAt: identity2.updatedAt
+    };
+  }
+  return {
+    version: 1,
+    workspaceRef: record.workspaceRef,
+    workspaceName: record.workspaceName,
+    identities: normalizedIdentities
+  };
+}
+async function readOptionalAgentIdentityCache(filePath) {
+  const file = Bun.file(filePath);
+  if (!await file.exists()) {
+    return null;
+  }
+  return parseAgentIdentityCache(await file.text(), filePath);
+}
+function agentIdentityCachePath(config, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const cadenceDirectory = config.localConfigPath ? dirname(config.localConfigPath) : config.repoConfigPath ? dirname(config.repoConfigPath) : join(cwd, ".cadence");
+  return join(cadenceDirectory, "agent-identities.json");
+}
+async function writeAgentIdentityCache(filePath, cache) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(cache, null, 2)}
+`);
+}
+async function ensureWorkspaceAgentIdentity(parsed, config, client, options) {
+  const projectId = requireProjectId(config);
+  const agentKind = requireOption(parsed, "agent-kind");
+  const filePath = agentIdentityCachePath(config, options);
+  const existing = await readOptionalAgentIdentityCache(filePath);
+  const explicitWorkspaceRef = parsed.options["workspace-ref"];
+  const workspaceRef = explicitWorkspaceRef ?? existing?.workspaceRef ?? `local:${randomUUID()}`;
+  const workspaceName = parsed.options["workspace-name"] ?? existing?.workspaceName ?? basename(options.cwd ?? process.cwd());
+  const identities = explicitWorkspaceRef && existing && explicitWorkspaceRef !== existing.workspaceRef ? {} : { ...existing?.identities ?? {} };
+  const ensured = await client.actors.ensureWorkspaceAgent({
+    projectId,
+    workspaceRef,
+    workspaceName,
+    agentKind,
+    ...parsed.options["display-name"] ? { displayName: parsed.options["display-name"] } : {}
+  });
+  const updatedAt = new Date().toISOString();
+  const cache = {
+    version: 1,
+    workspaceRef,
+    workspaceName,
+    identities: {
+      ...identities,
+      [agentKind]: {
+        actorId: ensured.actorId,
+        displayName: ensured.displayName,
+        kind: "agent",
+        agentKind: ensured.agentKind,
+        updatedAt
+      }
+    }
+  };
+  await writeAgentIdentityCache(filePath, cache);
+  return {
+    ...cache.identities[agentKind],
+    workspaceRef: cache.workspaceRef,
+    workspaceName: cache.workspaceName
+  };
+}
+async function findRepoCadenceDirectory(cwd) {
   let current = cwd;
   while (true) {
-    const candidate = join(current, ".cadence", "config.json");
-    if (await Bun.file(candidate).exists()) {
-      return candidate;
+    const cadenceDirectory = join(current, ".cadence");
+    const repoConfig = join(cadenceDirectory, "config.json");
+    const localConfig = join(cadenceDirectory, "config.local.json");
+    if (await Bun.file(repoConfig).exists() || await Bun.file(localConfig).exists()) {
+      return cadenceDirectory;
     }
     const parent = dirname(current);
     if (parent === current) {
@@ -1666,18 +1829,34 @@ async function resolveCliConfig(flags, options = {}) {
   const env = options.env ?? process.env;
   const cwd = options.cwd ?? process.cwd();
   const globalConfigPath = join(getConfigHome(env), "config.json");
-  const repoConfigPath = await findRepoConfigPath(cwd);
+  const repoCadenceDirectory = await findRepoCadenceDirectory(cwd);
+  const repoConfigPath = repoCadenceDirectory ? join(repoCadenceDirectory, "config.json") : null;
+  const localConfigPath = repoCadenceDirectory ? join(repoCadenceDirectory, "config.local.json") : null;
   const repoConfigPromise = repoConfigPath ? readOptionalConfig(repoConfigPath) : Promise.resolve({});
-  const [globalConfig, repoConfig] = await Promise.all([
+  const localConfigPromise = localConfigPath ? readOptionalConfig(localConfigPath) : Promise.resolve({});
+  const [globalConfig, repoConfig, localConfig] = await Promise.all([
     readOptionalConfig(globalConfigPath),
-    repoConfigPromise
+    repoConfigPromise,
+    localConfigPromise
   ]);
-  const server = flags.server ?? repoConfig.server ?? globalConfig.server ?? defaultCliApiBaseUrl;
-  const projectId = flags.project ?? repoConfig.projectId ?? globalConfig.projectId ?? null;
+  const profiles = {
+    ...globalConfig.profiles ?? {},
+    ...repoConfig.profiles ?? {},
+    ...localConfig.profiles ?? {}
+  };
+  const envProfile = env.CADENCE_PROFILE;
+  const profile = envProfile ?? localConfig.profile ?? repoConfig.profile ?? globalConfig.profile ?? null;
+  const profileConfig = profile ? profiles[profile] : undefined;
+  const server = flags.server ?? env.CADENCE_SERVER ?? localConfig.server ?? profileConfig?.server ?? repoConfig.server ?? globalConfig.server ?? defaultCliApiBaseUrl;
+  const webBaseUrl = env.CADENCE_WEB_BASE_URL ?? localConfig.webBaseUrl ?? profileConfig?.webBaseUrl ?? repoConfig.webBaseUrl ?? globalConfig.webBaseUrl ?? deriveWebBaseUrl(server);
+  const projectId = flags.project ?? localConfig.projectId ?? repoConfig.projectId ?? globalConfig.projectId ?? null;
   return {
     server,
+    webBaseUrl,
+    profile,
     projectId,
     repoConfigPath,
+    localConfigPath,
     globalConfigPath
   };
 }
@@ -1724,8 +1903,55 @@ function getCredentialStore(options) {
 async function readPromptText(options, message) {
   return options.readText ? options.readText(message) : promptText(message);
 }
-async function readPromptSecret(options, message) {
-  return options.readSecret ? options.readSecret(message) : promptSecret(message);
+function isInteractive(options) {
+  return options.isInteractive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+function getCliWebBaseUrl(config, parsed, options) {
+  return parsed.options["web-base-url"] ?? options.env?.CADENCE_WEB_BASE_URL ?? process.env.CADENCE_WEB_BASE_URL ?? config.webBaseUrl;
+}
+function deriveWebBaseUrl(server) {
+  try {
+    const url = new URL(server);
+    if ((url.hostname === "localhost" || url.hostname === "127.0.0.1") && url.port === "3000") {
+      url.port = "3001";
+      return url.toString().replace(/\/$/, "");
+    }
+  } catch {
+    return defaultCliWebBaseUrl;
+  }
+  return defaultCliWebBaseUrl;
+}
+async function openBrowser(url, options) {
+  if (options.openBrowser) {
+    await options.openBrowser(url);
+    return;
+  }
+  if (process.platform === "darwin") {
+    const result = spawnSync("open", [url]);
+    if (result.status !== 0) {
+      throw new CliError("BROWSER_OPEN_FAILED", "Could not open the browser for Cadence login.", {
+        loginUrl: url
+      });
+    }
+  }
+}
+async function sleep2(milliseconds, options) {
+  if (options.sleep) {
+    await options.sleep(milliseconds);
+    return;
+  }
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function writeInteractiveStatus(message, options) {
+  if (!isInteractive(options)) {
+    return;
+  }
+  if (options.writeStatus) {
+    await options.writeStatus(message);
+    return;
+  }
+  process.stderr.write(`${message}
+`);
 }
 function encodeCredential(credential) {
   return JSON.stringify(credential);
@@ -1754,6 +1980,68 @@ async function readStoredCredential(store, server) {
   const rawCredential = await store.getCredential(server);
   return rawCredential ? decodeCredential(rawCredential) : null;
 }
+function normalizeServerForCredentialLock(server) {
+  try {
+    return new URL(server).toString().replace(/\/$/, "");
+  } catch {
+    return server.trim();
+  }
+}
+function credentialRefreshLockPath(config) {
+  const normalizedServer = normalizeServerForCredentialLock(config.server);
+  const serverHash = createHash("sha256").update(normalizedServer).digest("hex").slice(0, 24);
+  return join(dirname(config.globalConfigPath), "locks", `credential-refresh-${serverHash}.lock`);
+}
+async function waitForCredentialRefreshLockPoll() {
+  await new Promise((resolve) => setTimeout(resolve, credentialRefreshLockPollMs));
+}
+async function removeStaleCredentialRefreshLock(lockPath, now) {
+  try {
+    const lockStats = await stat(lockPath);
+    if (now - lockStats.mtimeMs < credentialRefreshLockStaleMs) {
+      return false;
+    }
+    await rm(lockPath, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function acquireCredentialRefreshLock(config) {
+  const lockPath = credentialRefreshLockPath(config);
+  const deadline = Date.now() + credentialRefreshLockTimeoutMs;
+  await mkdir(dirname(lockPath), { recursive: true });
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      await writeFile(join(lockPath, "holder.json"), `${JSON.stringify({
+        pid: process.pid,
+        server: normalizeServerForCredentialLock(config.server),
+        acquiredAt: new Date().toISOString()
+      }, null, 2)}
+`);
+      return { path: lockPath };
+    } catch (error) {
+      if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+        throw error;
+      }
+      const now = Date.now();
+      const removedStaleLock = await removeStaleCredentialRefreshLock(lockPath, now);
+      if (!removedStaleLock && now >= deadline) {
+        throw new CliError("AUTH_REFRESH_LOCK_TIMEOUT", "Timed out waiting for another Cadence credential refresh to finish.", {
+          server: config.server
+        });
+      }
+      await waitForCredentialRefreshLockPoll();
+    }
+  }
+}
+async function releaseCredentialRefreshLock(lock) {
+  await rm(lock.path, { recursive: true, force: true });
+}
 async function requireCredentialStore(store) {
   if (!await store.isAvailable()) {
     throw new CliError("CREDENTIAL_STORE_UNAVAILABLE", "OS secure credential storage is unavailable.");
@@ -1773,19 +2061,6 @@ async function promptText(message) {
     readline.close();
   }
 }
-async function promptSecret(message) {
-  if (!process.stdin.isTTY || !process.stderr.isTTY) {
-    throw new CliError("AUTH_INTERACTIVE_REQUIRED", "Interactive auth requires a TTY.");
-  }
-  spawnSync("stty", ["-echo"], { stdio: ["inherit", "ignore", "ignore"] });
-  try {
-    return await promptText(message);
-  } finally {
-    spawnSync("stty", ["echo"], { stdio: ["inherit", "ignore", "ignore"] });
-    process.stderr.write(`
-`);
-  }
-}
 function successEnvelope(data, meta) {
   return {
     success: true,
@@ -1816,11 +2091,13 @@ function helpText() {
     "Cadence CLI",
     "",
     "Usage:",
-    "  cadence init --project <project-id> [--json]",
+    "  cadence init [--project <project-id|org/project>] [--json]",
     "  cadence auth login [--json]",
     "  cadence auth status [--json]",
     "  cadence auth logout [--json]",
+    "  cadence actors ensure-workspace-agent --agent-kind <kind> [--workspace-name <name>] [--workspace-ref <ref>] [--display-name <name>] [--project <project-id>] [--json]",
     "  cadence status [--project <project-id>] [--json]",
+    "  cadence projects list [--json]",
     "  cadence work overview [--project <project-id>] [--json]",
     "  cadence tickets get <ticket-id> [--project <project-id>] [--json]",
     "  cadence tickets list [--project <project-id>] [--status <status>] [--json]",
@@ -1828,36 +2105,103 @@ function helpText() {
     "  cadence tickets attach <ticket-id> --from-intake <intake-id> --if-version <version> [--project <project-id>] [--json]",
     "  cadence tickets create --title <text> [--from-intake <intake-id>] [--project <project-id>] [--json]",
     "  cadence tickets update <ticket-id> --if-version <version> [--title <text>] [--description <text>] [--priority <priority>] [--status <status>] [--project <project-id>] [--json]",
-    "  cadence tickets claim <ticket-id> --session <session-id> [--project <project-id>] [--json]",
+    "  cadence tickets claim <ticket-id> --session <session-id> [--actor <actor-id>] [--project <project-id>] [--json]",
     "  cadence tickets release <ticket-id> --lease <lease-id> [--project <project-id>] [--json]",
+    "  cadence tickets log <ticket-id> --kind <intent|decision|rationale|action|verification|blocker|correction|note> --body <text> [--summary <text>] [--under <entry-id|ticket-last|session-last|last-decision|last-correction|last-action>] [--session <session-id>] [--changeset <changeset-id>] [--project <project-id>] [--json]",
     "  cadence tickets complete <ticket-id> --if-version <version> [--summary <summary>] [--project <project-id>] [--json]",
-    "  cadence sessions start --ticket <ticket-id> [--changeset <changeset-id>] [--project <project-id>] [--json]",
+    "  cadence sessions start --ticket <ticket-id> [--changeset <changeset-id>] [--actor <actor-id>] [--project <project-id>] [--json]",
     "  cadence sessions end <session-id> --summary <summary> [--project <project-id>] [--json]",
+    "  cadence sessions files <session-id> --file <path> [--file <path>] [--kind <added|modified|deleted|renamed|unknown>] [--changeset <changeset-id>] [--project <project-id>] [--json]",
     "  cadence changesets create --ticket <ticket-id> --branch <branch> [--base-branch <branch>] [--project <project-id>] [--json]",
     "  cadence intake dismiss <intake-id> --reason <reason> [--project <project-id>] [--json]",
     "  cadence sessions current [--project <project-id>] [--ticket <ticket-id>] [--changeset <changeset-id>] [--json]",
+    "  cadence changesets current [--branch current|<branch>] [--project <project-id>] [--json]",
     "  cadence changesets get <changeset-id> [--project <project-id>] [--json]",
     "  cadence changesets list [--project <project-id>] [--ticket <ticket-id>] [--status <status>] [--json]",
+    "  cadence changesets notes get [--changeset <id>|--branch current|<branch>] [--project <project-id>] [--json]",
+    "  cadence changesets notes put [--changeset <id>|--branch current|<branch>] --title <text> --body-file <path> [--head-sha <sha>] [--base-sha <sha>] [--pr-url <url>] [--pr-number <n>] [--project <project-id>] [--json]",
+    "  cadence changesets notes apply [--changeset <id>|--branch current|<branch>] --provider github --pr-number <n> --pr-url <url> [--project <project-id>] [--json]",
     "  cadence events list [--project <project-id>] [--ticket <ticket-id>] [--changeset <changeset-id>] [--session <session-id>] [--json]",
     "",
     "Global flags:",
-    "  --project <id>       Cadence project ID",
+    "  --project <id>       Cadence project ID or org/project slug",
+    "  --server <url>       Cadence API server override",
     "  --json               Print stable JSON envelope",
     "",
+    "Work log parent selectors:",
+    "  --under ticket-last attaches under the latest work-log entry on the Ticket.",
+    "  --under session-last attaches under the latest entry in --session.",
+    "  --under last-decision|last-correction|last-action attaches under the latest matching kind.",
+    "  --under last is only valid with --session; without a session use ticket-last or a kind selector.",
+    "",
     "Auth options:",
-    "  --email <email>       Email for auth login"
+    "  --web-base-url <url> Browser login base URL"
   ].join(`
 `);
 }
+function credentialExpiresSoon(credential, now = new Date) {
+  if (!credential.expiresAt) {
+    return false;
+  }
+  const expiresAt = new Date(credential.expiresAt).getTime();
+  if (Number.isNaN(expiresAt)) {
+    return false;
+  }
+  return expiresAt <= now.getTime() + credentialRefreshSkewMs;
+}
+async function readFreshAccessToken(config, store, authClient) {
+  const credential = await readStoredCredential(store, config.server);
+  if (!credential) {
+    return "";
+  }
+  if (!credentialExpiresSoon(credential)) {
+    return credential.accessToken;
+  }
+  const lock = await acquireCredentialRefreshLock(config);
+  try {
+    const lockedCredential = await readStoredCredential(store, config.server);
+    if (!lockedCredential) {
+      return "";
+    }
+    if (!credentialExpiresSoon(lockedCredential)) {
+      return lockedCredential.accessToken;
+    }
+    if (!lockedCredential.refreshToken) {
+      throw new CliError("AUTH_REFRESH_REQUIRED", "Stored Cadence credential is expired and cannot be refreshed because no refresh token is stored.");
+    }
+    try {
+      const refreshed = await authClient.auth.cli.refresh({
+        refreshToken: lockedCredential.refreshToken
+      });
+      await store.setCredential(config.server, encodeCredential(refreshed));
+      return refreshed.accessToken;
+    } catch (error) {
+      const recoveredCredential = await readStoredCredential(store, config.server);
+      if (recoveredCredential && !credentialExpiresSoon(recoveredCredential)) {
+        return recoveredCredential.accessToken;
+      }
+      throw new CliError("AUTH_REFRESH_FAILED", "Stored Cadence credential is expired and refresh failed. Run `cadence auth login` to reconnect.", {
+        server: config.server,
+        cause: error instanceof Error ? error.message : "Credential refresh failed."
+      });
+    }
+  } finally {
+    await releaseCredentialRefreshLock(lock);
+  }
+}
 async function createClient(config, options) {
   if (options.client) {
     return options.client;
   }
   const store = getCredentialStore(options);
   const credential = await readStoredCredential(store, config.server);
+  const authClient = createCadenceClient({
+    baseUrl: config.server,
+    ...options.fetch ? { fetch: options.fetch } : {}
+  });
   return createCadenceClient({
     baseUrl: config.server,
-    ...credential ? { getAuthToken: async () => (await readStoredCredential(store, config.server))?.accessToken ?? "" } : {},
+    ...credential ? { getAuthToken: async () => readFreshAccessToken(config, store, authClient) } : {},
     ...options.fetch ? { fetch: options.fetch } : {}
   });
 }
@@ -1865,6 +2209,7 @@ function commandMeta(parsed, config) {
   return {
     command: parsed.command.name,
     server: config.server,
+    ...config.profile ? { profile: config.profile } : {},
     projectId: config.projectId
   };
 }
@@ -1926,6 +2271,55 @@ function parseTicketStatus(value) {
   }
   return value;
 }
+function parseSessionFileChangeKind(value) {
+  if (!value) {
+    return "unknown";
+  }
+  if (sessionFileChangeKinds.includes(value)) {
+    return value;
+  }
+  throw new CliError("CLI_USAGE", "--kind must be one of added, modified, deleted, renamed, or unknown.");
+}
+function parseChangeSetPrNoteSource(value) {
+  if (!value) {
+    return;
+  }
+  if (changesetPrNoteSources.includes(value)) {
+    return value;
+  }
+  throw new CliError("CLI_USAGE", "--source must be one of agent, human, system.");
+}
+function parseWorkLogEntryKind(value) {
+  if (!value) {
+    throw new CliError("CLI_USAGE", "--kind must be one of intent, decision, rationale, action, verification, blocker, correction, or note.");
+  }
+  if (workLogEntryKinds.includes(value)) {
+    return value;
+  }
+  throw new CliError("CLI_USAGE", "--kind must be one of intent, decision, rationale, action, verification, blocker, correction, or note.");
+}
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function parseWorkLogParent(value) {
+  if (!value) {
+    return {};
+  }
+  if (uuidPattern.test(value)) {
+    return { parentEntryId: value };
+  }
+  if (workLogParentSelectors.includes(value)) {
+    return { parentSelector: value };
+  }
+  throw new CliError("CLI_USAGE", "--under must be a work-log entry UUID or one of ticket-last, session-last, last-decision, last-correction, last-action, or last.");
+}
+function parseSessionFilePaths(parsed) {
+  const value = requireOption(parsed, "file");
+  const paths = value.split(`
+`).map((path) => path.trim()).filter(Boolean);
+  if (paths.length === 0) {
+    throw new CliError("CLI_USAGE", "sessions files requires at least one --file.");
+  }
+  return paths;
+}
 function leaseExpiresAt(ttlSeconds) {
   return new Date(Date.now() + ttlSeconds * 1000).toISOString();
 }
@@ -1938,20 +2332,73 @@ function commandMetadata() {
     source: "cli"
   };
 }
+function notesCommandMetadata() {
+  return {
+    occurredAt: new Date().toISOString(),
+    eventSource: "cli"
+  };
+}
+async function resolveCurrentBranch(options) {
+  const injected = await options.resolveCurrentBranch?.();
+  if (injected !== undefined) {
+    const branch2 = injected.trim();
+    if (!branch2) {
+      throw new CliError("GIT_BRANCH_ERROR", "Current git branch is empty.");
+    }
+    return branch2;
+  }
+  const result = spawnSync("git", ["branch", "--show-current"], {
+    cwd: options.cwd,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    throw new CliError("GIT_BRANCH_ERROR", "Failed to resolve current git branch.", {
+      stderr: result.stderr?.trim() ?? ""
+    });
+  }
+  const branch = result.stdout.trim();
+  if (!branch) {
+    throw new CliError("GIT_BRANCH_ERROR", "Current git branch is empty.");
+  }
+  return branch;
+}
+async function changesetLookupFromOptions(parsed, options) {
+  if (parsed.options.changeset && parsed.options.branch) {
+    throw new CliError("CLI_USAGE", "Use either --changeset or --branch, not both.");
+  }
+  if (parsed.options.changeset) {
+    return {
+      changesetId: parsed.options.changeset
+    };
+  }
+  const branchOption = parsed.options.branch ?? "current";
+  const branchName = branchOption === "current" ? await resolveCurrentBranch(options) : branchOption;
+  return {
+    branchName
+  };
+}
+async function readBodyFile(path, options) {
+  const resolvedPath = isAbsolute(path) ? path : join(options.cwd ?? process.cwd(), path);
+  return readFile(resolvedPath, "utf8");
+}
 async function runStatus(parsed, options) {
   const config = await resolveCliConfig(parsed.flags, options);
   const store = getCredentialStore(options);
   const credential = await readStoredCredential(store, config.server);
   const client = await createClient(config, options);
   const health = await client.health();
+  const webBaseUrl = getCliWebBaseUrl(config, parsed, options);
   const data = {
     server: config.server,
+    webBaseUrl,
+    profile: config.profile,
     projectId: config.projectId,
     credentialConfigured: Boolean(credential),
     authTokenConfigured: Boolean(credential),
     health,
     config: {
       repoConfigPath: config.repoConfigPath,
+      localConfigPath: config.localConfigPath,
       globalConfigPath: config.globalConfigPath
     }
   };
@@ -1973,25 +2420,28 @@ async function runStatus(parsed, options) {
 async function runInit(parsed, options) {
   const cwd = options.cwd ?? process.cwd();
   const repoConfigPath = join(cwd, ".cadence", "config.json");
-  const projectId = parsed.flags.project;
-  if (!projectId) {
-    throw new CliError("CLI_USAGE", "init requires --project.");
-  }
+  const config = await resolveCliConfig(parsed.flags, {
+    ...options,
+    cwd
+  });
+  const client = await createClient(config, options);
+  const project = await selectProject(parsed, client, options);
+  const projectId = project.id;
   const updates = {
     projectId,
     ...parsed.flags.server ? { server: parsed.flags.server } : {}
   };
   await mergeConfigFile(repoConfigPath, updates);
-  const config = await resolveCliConfig(parsed.flags, {
-    ...options,
-    cwd
-  });
   const data = {
     repoConfigPath,
     projectId,
+    project,
     ...parsed.flags.server ? { server: parsed.flags.server } : {}
   };
-  const meta = commandMeta(parsed, config);
+  const meta = commandMeta(parsed, {
+    ...config,
+    projectId
+  });
   if (parsed.flags.json) {
     return {
       stdout: formatJson(successEnvelope(data, meta)),
@@ -2006,6 +2456,69 @@ async function runInit(parsed, options) {
     exitCode: 0
   };
 }
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+async function resolveProjectReference(projectReference, client) {
+  if (isUuid(projectReference)) {
+    return {
+      id: projectReference,
+      orgSlug: null,
+      projectSlug: null,
+      name: null
+    };
+  }
+  const [orgSlug, projectSlug, extra] = projectReference.split("/");
+  if (!orgSlug || !projectSlug || extra) {
+    throw new CliError("CLI_USAGE", "--project must be a project ID or org/project slug.");
+  }
+  return await client.projects.resolve({
+    orgSlug,
+    projectSlug
+  });
+}
+function formatProjectChoice(project, index) {
+  const slug = project.orgSlug && project.projectSlug ? `${project.orgSlug}/${project.projectSlug}` : project.id;
+  const name = project.name ? ` ${project.name}` : "";
+  return `${index + 1}. ${slug}${name}`;
+}
+async function selectProject(parsed, client, options) {
+  if (parsed.flags.project) {
+    return await resolveProjectReference(parsed.flags.project, client);
+  }
+  const projects = await client.projects.list();
+  if (projects.length === 1) {
+    return projects[0];
+  }
+  if (parsed.flags.json || !isInteractive(options)) {
+    throw new CliError("PROJECT_REQUIRED", "Choose a Cadence project with --project.", {
+      projects
+    });
+  }
+  if (projects.length === 0) {
+    throw new CliError("PROJECT_REQUIRED", "No accessible Cadence projects were found.");
+  }
+  const message = [
+    "Choose a Cadence project:",
+    ...projects.map(formatProjectChoice),
+    "",
+    "Project number, ID, or org/project: "
+  ].join(`
+`);
+  const answer = (await readPromptText(options, message)).trim();
+  const selectedIndex = Number(answer);
+  const selected = Number.isInteger(selectedIndex) && selectedIndex > 0 ? projects[selectedIndex - 1] : undefined;
+  if (selected) {
+    return selected;
+  }
+  const matching = projects.find((project) => project.id === answer || `${project.orgSlug}/${project.projectSlug}` === answer);
+  if (!matching) {
+    throw new CliError("PROJECT_REQUIRED", "Selected project was not in the accessible project list.", {
+      projects
+    });
+  }
+  return matching;
+}
 async function runAuthCommand(parsed, options) {
   const config = await resolveCliConfig(parsed.flags, options);
   const store = getCredentialStore(options);
@@ -2014,18 +2527,48 @@ async function runAuthCommand(parsed, options) {
   switch (parsed.command.name) {
     case "auth.login":
       {
-        await requireCredentialStore(store);
         const client = await createClient(config, options);
-        const credential = await client.auth.login({
-          email: parsed.options.email ?? await readPromptText(options, "Email: "),
-          password: await readPromptSecret(options, "Password: ")
+        const challenge = await client.auth.cli.start({
+          loginBaseUrl: getCliWebBaseUrl(config, parsed, options)
         });
-        await store.setCredential(config.server, encodeCredential(credential));
+        if (parsed.flags.json || !isInteractive(options)) {
+          throw new CliError("HUMAN_AUTH_REQUIRED", "Cadence login must be completed by a human in the browser.", {
+            loginUrl: challenge.loginUrl,
+            deviceCode: challenge.deviceCode,
+            expiresAt: challenge.expiresAt
+          });
+        }
+        await requireCredentialStore(store);
+        await writeInteractiveStatus("Opening browser to approve Cadence CLI access.", options);
+        await writeInteractiveStatus(`Verification code: ${challenge.deviceCode}`, options);
+        await writeInteractiveStatus(`Login URL: ${challenge.loginUrl}`, options);
+        await openBrowser(challenge.loginUrl, options);
+        await writeInteractiveStatus("Waiting for browser approval...", options);
+        let poll = await client.auth.cli.poll({
+          deviceId: challenge.deviceId,
+          deviceCode: challenge.deviceCode
+        });
+        while (poll.status === "pending") {
+          await sleep2(poll.pollIntervalSeconds * 1000, options);
+          poll = await client.auth.cli.poll({
+            deviceId: challenge.deviceId,
+            deviceCode: challenge.deviceCode
+          });
+        }
+        if (poll.status === "expired") {
+          throw new CliError("AUTH_LOGIN_EXPIRED", "Cadence browser login expired.");
+        }
+        if (poll.status === "denied") {
+          throw new CliError("AUTH_LOGIN_DENIED", "Cadence browser login was denied.");
+        }
+        await store.setCredential(config.server, encodeCredential(poll.credential));
         await mergeConfigFile(config.globalConfigPath, { server: config.server });
+        await writeInteractiveStatus("Cadence CLI login approved. Credential stored.", options);
         data = {
           server: config.server,
           credentialStored: true,
-          globalConfigPath: config.globalConfigPath
+          globalConfigPath: config.globalConfigPath,
+          loginUrl: challenge.loginUrl
         };
       }
       break;
@@ -2125,6 +2668,12 @@ async function runReadCommand(parsed, options) {
         changesetId: requireArg(parsed, 0, "<changeset-id>")
       });
       break;
+    case "changesets.current":
+      data = await client.changesets.context({
+        projectId,
+        query: await changesetLookupFromOptions(parsed, options)
+      });
+      break;
     case "changesets.list":
       data = await client.changesets.list({
         projectId,
@@ -2136,6 +2685,64 @@ async function runReadCommand(parsed, options) {
         })
       });
       break;
+    case "changesets.notes.get":
+      data = await client.changesets.notes.get({
+        projectId,
+        query: await changesetLookupFromOptions(parsed, options)
+      });
+      break;
+    default:
+      throw new CliError("CLI_USAGE", `Unknown command: ${parsed.command.path.join(" ")}`);
+  }
+  if (parsed.flags.json) {
+    return {
+      stdout: formatJson(successEnvelope(data, meta)),
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: `${JSON.stringify(data, null, 2)}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runProjectCommand(parsed, options) {
+  const config = await resolveCliConfig(parsed.flags, options);
+  const client = await createClient(config, options);
+  const meta = commandMeta(parsed, config);
+  let data;
+  switch (parsed.command.name) {
+    case "projects.list":
+      data = await client.projects.list();
+      break;
+    default:
+      throw new CliError("CLI_USAGE", `Unknown command: ${parsed.command.path.join(" ")}`);
+  }
+  if (parsed.flags.json) {
+    return {
+      stdout: formatJson(successEnvelope(data, meta)),
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: `${JSON.stringify(data, null, 2)}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runActorCommand(parsed, options) {
+  const config = await resolveCliConfig(parsed.flags, options);
+  const client = await createClient(config, options);
+  const meta = commandMeta(parsed, config);
+  let data;
+  switch (parsed.command.name) {
+    case "actors.ensure-workspace-agent":
+      data = await ensureWorkspaceAgentIdentity(parsed, config, client, options);
+      break;
     default:
       throw new CliError("CLI_USAGE", `Unknown command: ${parsed.command.path.join(" ")}`);
   }
@@ -2249,6 +2856,7 @@ async function runIntakeCommand(parsed, options) {
           ticketId: requireArg(parsed, 0, "<ticket-id>"),
           sessionId: requireOption(parsed, "session"),
           ...parsed.options.changeset ? { changesetId: parsed.options.changeset } : {},
+          ...parsed.options.actor ? { actorId: parsed.options.actor } : {},
           expiresAt: leaseExpiresAt(parsePositiveInteger(parsed.options["ttl-seconds"], "--ttl-seconds") ?? defaultLeaseTtlSeconds),
           ...commandMetadata()
         }
@@ -2265,6 +2873,21 @@ async function runIntakeCommand(parsed, options) {
         }
       });
       break;
+    case "tickets.log":
+      data = await client.tickets.log({
+        projectId,
+        ticketId: requireArg(parsed, 0, "<ticket-id>"),
+        entry: {
+          entryKind: parseWorkLogEntryKind(parsed.options.kind),
+          body: requireOption(parsed, "body"),
+          ...parsed.options.summary ? { summary: parsed.options.summary } : {},
+          ...parseWorkLogParent(parsed.options.under),
+          ...parsed.options.session ? { sessionId: parsed.options.session } : {},
+          ...parsed.options.changeset ? { changesetId: parsed.options.changeset } : {},
+          ...commandMetadata()
+        }
+      });
+      break;
     case "tickets.complete":
       data = await client.tickets.complete({
         projectId,
@@ -2282,6 +2905,7 @@ async function runIntakeCommand(parsed, options) {
         session: {
           ticketId: requireOption(parsed, "ticket"),
           ...parsed.options.changeset ? { changesetId: parsed.options.changeset } : {},
+          ...parsed.options.actor ? { actorId: parsed.options.actor } : {},
           ...parsed.options["local-session-ref"] ? { localSessionRef: parsed.options["local-session-ref"] } : {},
           ...commandMetadata()
         }
@@ -2297,6 +2921,23 @@ async function runIntakeCommand(parsed, options) {
         }
       });
       break;
+    case "sessions.files":
+      {
+        const changeKind = parseSessionFileChangeKind(parsed.options.kind);
+        data = await client.sessions.files({
+          projectId,
+          sessionId: requireArg(parsed, 0, "<session-id>"),
+          files: {
+            ...parsed.options.changeset ? { changesetId: parsed.options.changeset } : {},
+            files: parseSessionFilePaths(parsed).map((path) => ({
+              path,
+              changeKind
+            })),
+            ...commandMetadata()
+          }
+        });
+      }
+      break;
     case "changesets.create":
       data = await client.changesets.create({
         projectId,
@@ -2309,6 +2950,41 @@ async function runIntakeCommand(parsed, options) {
         }
       });
       break;
+    case "changesets.notes.put":
+      {
+        const source = parseChangeSetPrNoteSource(parsed.options.source);
+        data = await client.changesets.notes.put({
+          projectId,
+          query: await changesetLookupFromOptions(parsed, options),
+          notes: {
+            title: requireOption(parsed, "title"),
+            body: await readBodyFile(requireOption(parsed, "body-file"), options),
+            ...source ? { source } : {},
+            ...parsed.options.provider ? { prProvider: parsed.options.provider } : {},
+            ...parsed.options["pr-number"] ? { prNumber: parseRequiredPositiveInteger(parsed.options["pr-number"], "--pr-number") } : {},
+            ...parsed.options["pr-url"] ? { prUrl: parsed.options["pr-url"] } : {},
+            ...parsed.options["base-branch"] ? { baseBranch: parsed.options["base-branch"] } : {},
+            ...parsed.options["head-branch"] ? { headBranch: parsed.options["head-branch"] } : {},
+            ...parsed.options["base-sha"] ? { baseSha: parsed.options["base-sha"] } : {},
+            ...parsed.options["head-sha"] ? { headSha: parsed.options["head-sha"] } : {},
+            ...notesCommandMetadata()
+          }
+        });
+      }
+      break;
+    case "changesets.notes.apply":
+      data = await client.changesets.notes.apply({
+        projectId,
+        query: await changesetLookupFromOptions(parsed, options),
+        notes: {
+          prProvider: requireOption(parsed, "provider"),
+          prNumber: parseRequiredPositiveInteger(requireOption(parsed, "pr-number"), "--pr-number"),
+          prUrl: requireOption(parsed, "pr-url"),
+          ...parsed.options["head-sha"] ? { headSha: parsed.options["head-sha"] } : {},
+          ...notesCommandMetadata()
+        }
+      });
+      break;
     default:
       throw new CliError("CLI_USAGE", `Unknown command: ${parsed.command.path.join(" ")}`);
   }
@@ -2370,13 +3046,19 @@ async function runCli(argv, options = {}) {
     if (parsed.command.name === "init") {
       return await runInit(parsed, options);
     }
+    if (parsed.command.name === "actors.ensure-workspace-agent") {
+      return await runActorCommand(parsed, options);
+    }
     if (parsed.command.name === "auth.login" || parsed.command.name === "auth.status" || parsed.command.name === "auth.logout") {
       return await runAuthCommand(parsed, options);
     }
-    if (parsed.command.name === "events.list" || parsed.command.name === "work.overview" || parsed.command.name === "tickets.get" || parsed.command.name === "tickets.list" || parsed.command.name === "sessions.current" || parsed.command.name === "changesets.get" || parsed.command.name === "changesets.list") {
+    if (parsed.command.name === "events.list" || parsed.command.name === "work.overview" || parsed.command.name === "tickets.get" || parsed.command.name === "tickets.list" || parsed.command.name === "sessions.current" || parsed.command.name === "changesets.get" || parsed.command.name === "changesets.current" || parsed.command.name === "changesets.list" || parsed.command.name === "changesets.notes.get") {
       return await runReadCommand(parsed, options);
     }
-    if (parsed.command.name === "intake" || parsed.command.name === "intake.dismiss" || parsed.command.name === "tickets.attach" || parsed.command.name === "tickets.create" || parsed.command.name === "tickets.update" || parsed.command.name === "tickets.claim" || parsed.command.name === "tickets.release" || parsed.command.name === "tickets.complete" || parsed.command.name === "sessions.start" || parsed.command.name === "sessions.end" || parsed.command.name === "changesets.create") {
+    if (parsed.command.name === "projects.list") {
+      return await runProjectCommand(parsed, options);
+    }
+    if (parsed.command.name === "intake" || parsed.command.name === "intake.dismiss" || parsed.command.name === "tickets.attach" || parsed.command.name === "tickets.create" || parsed.command.name === "tickets.update" || parsed.command.name === "tickets.claim" || parsed.command.name === "tickets.release" || parsed.command.name === "tickets.log" || parsed.command.name === "tickets.complete" || parsed.command.name === "sessions.start" || parsed.command.name === "sessions.end" || parsed.command.name === "sessions.files" || parsed.command.name === "changesets.create" || parsed.command.name === "changesets.notes.put" || parsed.command.name === "changesets.notes.apply") {
       return await runIntakeCommand(parsed, options);
     }
     throw new CliError("CLI_USAGE", `Unknown command: ${parsed.command.path.join(" ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycadence/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "bin": {