tines 0.0.1 → 0.0.76

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync2, statSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { hostname as hostname2 } from "node:os";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { basename, dirname as dirname3, join as join3 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // src/daemon/daemon.ts
@@ -40,12 +40,46 @@ function repoDirFromUrl(url) {
   if (!base || base === "." || base === ".." || base.includes("\\") || base.includes("=")) return "repo";
   return base;
 }
+var ARTIFACT_FILE_MAX_BYTES = 25 * 1024 * 1024;
+var ARTIFACT_TEXT_MAX_BYTES = 256 * 1024;
+var ARTIFACT_FOLDER_MAX_BYTES = 50 * 1024 * 1024;
+function canonicalGitHubRepoUrl(url) {
+  const match = url.trim().match(
+    /^(?:(?:https?|ssh):\/\/(?:[^@/]+@)?|git@)?(?:www\.)?github\.com[/:]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/
+  );
+  if (!match) return null;
+  return `https://github.com/${match[1]}/${match[2]}`;
+}
+function parsePrSpec(spec) {
+  const short = spec.trim().match(/^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)$/);
+  if (short) {
+    const repoUrl2 = canonicalGitHubRepoUrl(`https://github.com/${short[1]}`);
+    return repoUrl2 ? { repo_url: repoUrl2, number: Number.parseInt(short[2], 10) } : null;
+  }
+  const url = spec.trim().match(/^(.*?)\/pull\/(\d+)(?:[/?#].*)?$/);
+  if (!url) return null;
+  const repoUrl = canonicalGitHubRepoUrl(url[1]);
+  return repoUrl ? { repo_url: repoUrl, number: Number.parseInt(url[2], 10) } : null;
+}
 var MODEL_TIERS = ["smartest", "balanced", "cheapest"];
 var RUNNER_ONLINE_WINDOW_MS = 2 * 60 * 1e3;
 var RUNNER_OFFLINE_FAIL_MS = 5 * 60 * 1e3;
 var LAUNCH_STALL_MS = 5 * 60 * 1e3;
 var RUN_KEY_SLACK_MS = 10 * 60 * 1e3;
 var RUN_LOG_MAX_BYTES = 256 * 1024;
+var MODEL_PREDECESSORS = {
+  "claude-fable-5": ["claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6"],
+  "claude-opus-5": ["claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5", "claude-opus-4-1"],
+  "claude-sonnet-5": ["claude-sonnet-4-6", "claude-sonnet-4-5", "claude-3-7-sonnet-latest"],
+  "claude-haiku-4-5": ["claude-3-5-haiku-latest"],
+  "gemini-2.5-pro": ["gemini-1.5-pro"],
+  "gemini-2.5-flash": ["gemini-2.0-flash", "gemini-1.5-flash"],
+  "gemini-2.5-flash-lite": ["gemini-2.0-flash-lite", "gemini-1.5-flash-8b"]
+};
+function isStaleTierOverride(builtinModel, overrideModel) {
+  if (!builtinModel || !overrideModel || builtinModel === overrideModel) return false;
+  return (MODEL_PREDECESSORS[builtinModel] ?? []).includes(overrideModel);
+}
 function runDurationLabel(run, now = Date.now()) {
   if (!run.started_at) return "\u2014";
   const seconds = Math.max(0, Math.round(((run.ended_at ?? now) - run.started_at) / 1e3));
@@ -116,6 +150,22 @@ function createApiClient(options) {
     return await res.json();
   }
   const get = (path) => request("GET", path);
+  async function raw(method, path, opts = {}) {
+    const headers = { ...opts.headers ?? {} };
+    if (options.apiKey) headers.authorization = `Bearer ${options.apiKey}`;
+    const body = opts.body instanceof Uint8Array ? opts.body.buffer.slice(opts.body.byteOffset, opts.body.byteOffset + opts.body.byteLength) : opts.body;
+    const res = await fetchFn(`${base}${path}`, { method, headers, body });
+    if (!res.ok) {
+      let parsed = null;
+      try {
+        parsed = (await res.json()).error ?? null;
+      } catch {
+      }
+      throw new ApiError(res.status, parsed, `${method} ${path} failed: ${res.status}`);
+    }
+    return res;
+  }
+  const artifactPath = (issueId, name, suffix = "") => `/api/v1/issues/${issueId}/artifacts/${encodeURIComponent(name)}${suffix}`;
   return {
     getTime: () => get("/api/time"),
     // Projects
@@ -166,8 +216,60 @@ function createApiClient(options) {
     appendContextItem: (id, body) => request("POST", `/api/v1/context/${id}/append`, body),
     /** Effective context for an issue: the assembled bundle. */
     getIssueContext: (issueId) => get(`/api/v1/issues/${issueId}/context`),
+    /**
+     * Which journal this caller's `tines journal` commands target — the
+     * run's launch state for a run key, the issue's current state otherwise.
+     */
+    getIssueJournal: (issueId) => get(`/api/v1/issues/${issueId}/journal`),
     /** Launch prompt: stitched context plus the generated issue block. */
     getIssuePrompt: (issueId) => get(`/api/v1/issues/${issueId}/prompt`),
+    // Issue artifacts (name-addressed under the issue)
+    listArtifacts: (issueId) => get(`/api/v1/issues/${issueId}/artifacts`),
+    getArtifact: (issueId, name) => get(artifactPath(issueId, name)),
+    /** JSON upsert for text/link/pr: creates the artifact or appends a version. */
+    putArtifact: (issueId, name, body) => request("PUT", artifactPath(issueId, name), body),
+    /** Raw-body upload for `file`: creates the artifact or appends a version. */
+    uploadArtifactFile: async (issueId, name, bytes, opts) => {
+      const res = await raw(
+        "PUT",
+        artifactPath(issueId, name, `/file?filename=${encodeURIComponent(opts.filename)}`),
+        {
+          body: bytes,
+          headers: { "content-type": opts.contentType }
+        }
+      );
+      return await res.json();
+    },
+    /**
+     * Multipart snapshot upload for `folder`: every file of the new version
+     * in one request (path as the part filename, MIME as the part type).
+     */
+    uploadArtifactFolder: async (issueId, name, files) => {
+      const form = new FormData();
+      for (const file of files) {
+        form.append("file", new Blob([file.bytes], { type: file.contentType }), file.path);
+      }
+      const res = await raw("PUT", artifactPath(issueId, name, "/folder"), { body: form });
+      return await res.json();
+    },
+    /** Bless the current content as fresh: appends a reaffirming version. */
+    reaffirmArtifact: (issueId, name) => request("POST", artifactPath(issueId, name, "/reaffirm")),
+    /** Bytes of a version (default: current; `path` selects a folder entry). */
+    getArtifactContent: async (issueId, name, opts = {}) => {
+      const params = new URLSearchParams();
+      if (opts.version !== void 0) params.set("version", String(opts.version));
+      if (opts.path !== void 0) params.set("path", opts.path);
+      const query2 = params.toString() ? `?${params.toString()}` : "";
+      const res = await raw("GET", artifactPath(issueId, name, `/content${query2}`));
+      const disposition = res.headers.get("content-disposition") ?? "";
+      const filenameMatch = disposition.match(/filename="((?:[^"\\]|\\.)*)"/);
+      return {
+        bytes: await res.arrayBuffer(),
+        content_type: res.headers.get("content-type"),
+        filename: filenameMatch ? filenameMatch[1].replaceAll('\\"', '"') : null
+      };
+    },
+    deleteArtifact: (issueId, name) => request("DELETE", artifactPath(issueId, name)),
     // Events
     listEvents: (filters = {}) => get(`/api/v1/events${query(filters)}`),
     // Runners
@@ -766,6 +868,17 @@ function reportError(err) {
       message2 += actions.length > 0 ? `
 allowed actions: ${actions.join(", ")}` : "\nallowed actions: none (terminal state)";
     }
+    const unmet = err.details?.unmet;
+    if (Array.isArray(unmet)) {
+      for (const raw of unmet) {
+        const r = raw;
+        const spec = [r.type, r.content_type].filter(Boolean).join(", ");
+        message2 += `
+requires artifact "${r.artifact}"${spec ? ` (${spec})` : ""}: ${r.status ?? "unmet"}${r.description ? ` \u2014 ${r.description}` : ""}`;
+        if (r.fix) message2 += `
+  fix: ${r.fix}`;
+      }
+    }
     die(message2);
   }
   die(err instanceof Error ? err.message : String(err));
@@ -861,6 +974,19 @@ existing sets wholesale when present.
 
 Each NEW state should carry a "prompt" \u2014 its initial stage instructions,
 created as a state-scoped context item \u2014 or pass --no-prompts to skip.
+
+A transition may declare artifact requirements ("requires"): it can then only
+be taken once a FRESH artifact with that name \u2014 attached (or reaffirmed)
+since the issue entered its current state \u2014 exists on the issue:
+
+  { "name": "approve", "from": "In review", "to": "Done",
+    "requires": [ { "artifact": "design-doc", "type": "file",
+                    "content_type": "text/markdown",
+                    "description": "The approved design for this round" } ] }
+
+"type" (file | text | link | pr) and "content_type" (a prefix match, e.g.
+"image/"; file/text only) are optional narrowing; "artifact" is the slot
+name issues must carry (see: tines issues artifacts --help).
 `;
 async function resolveProject(api, ref) {
   const { items } = await api.listProjects();
@@ -971,6 +1097,8 @@ function contextItemSummary(item) {
       return `${item.file_count ?? item.files?.length ?? 0} file${(item.file_count ?? item.files?.length ?? 0) === 1 ? "" : "s"}`;
     case "repo":
       return `${item.repo_url}${item.repo_branch ? `#${item.repo_branch}` : ""}`;
+    case "artifact":
+      return item.artifact_type ?? "artifact";
   }
 }
 function printContextItem(item) {
@@ -978,7 +1106,14 @@ function printContextItem(item) {
   if (item.description) console.log(item.description);
   console.log(`scope: ${item.scope.label}`);
   console.log(`updated: ${timestamp(item.updated_at)}  created: ${timestamp(item.created_at)}`);
-  if (item.kind === "prompt") {
+  if (item.kind === "artifact") {
+    console.log(`
+type: ${item.artifact_type ?? "artifact"}`);
+    if (item.scope.issue_ref) {
+      const ref = `${item.scope.issue_ref.project_name}/${item.scope.issue_ref.number}`;
+      console.log(`versions and content: tines issues artifacts show ${ref} ${item.name}`);
+    }
+  } else if (item.kind === "prompt") {
     console.log(`
 ${item.body}`);
   } else if (item.kind === "skill") {
@@ -1133,6 +1268,12 @@ function printWorkflowDetail(wf) {
     console.log(
       `  "${t.name}": ${byId.get(t.from_state_id)?.name} \u2192 ${byId.get(t.to_state_id)?.name}`
     );
+    for (const r of t.requires ?? []) {
+      const spec = [r.type, r.content_type].filter(Boolean).join(", ");
+      console.log(
+        `    requires artifact "${r.artifact}"${spec ? ` (${spec})` : ""}${r.description ? ` \u2014 ${r.description}` : ""}`
+      );
+    }
   }
   for (const w of wf.warnings ?? []) console.log(`
 warning: ${w}`);
@@ -1200,8 +1341,16 @@ function eventSummary(ev) {
       return ev.type;
   }
 }
+function cliVersion() {
+  try {
+    const manifest = new URL("../package.json", import.meta.url);
+    return JSON.parse(readFileSync2(manifest, "utf8")).version ?? "0.0.0-unknown";
+  } catch {
+    return "0.0.0-unknown";
+  }
+}
 var program = new Command();
-program.name("tines").description("CLI for Tines").version("0.0.1").enablePositionalOptions();
+program.name("tines").description("CLI for Tines").version(cliVersion()).enablePositionalOptions();
 withCommon(program.command("time").description("Fetch the current time from the Tines API")).action(
   async (opts) => {
     const result = await client(opts).getTime();
@@ -1362,7 +1511,7 @@ withCommon(
 });
 var issues = program.command("issues").description("Work with issues");
 withList(
-  issues.command("list").description("List issues across projects (hides done issues unless --all)").option("-p, --project <name>", "filter by project name or id").option("-s, --state <name>", "filter by state name or id").option("-c, --category <cat>", "filter by state category").option("-w, --workflow <id-or-name>", "filter by workflow").option("-a, --all", "include issues in done states").option("--ready", "only issues that are actionable now (not done, not a duplicate, no open blockers)")
+  issues.command("list").description("List issues across projects (hides done issues unless --all)").option("-p, --project <name>", "filter by project name or id").option("-s, --state <name>", "filter by state name or id").option("-c, --category <cat>", "filter by state category").option("-w, --workflow <id-or-name>", "filter by workflow").option("-a, --all", "include issues in done states").option("--ready", "only issues that are actionable now (not done, not a duplicate, no open blockers)").option("-q, --search <text>", "search titles and descriptions")
 ).action(
   async (opts) => {
     const res = await client(opts).listIssues({
@@ -1372,6 +1521,7 @@ withList(
       workflow: opts.workflow,
       hide_done: !opts.all,
       ready: opts.ready,
+      q: opts.search,
       limit: opts.limit,
       cursor: opts.cursor
     });
@@ -1597,6 +1747,274 @@ withCommon(
   if (opts.json) return printJson(prompt);
   console.log(prompt.text);
 });
+var artifactsCmd = issues.command("artifacts").description("Typed, versioned attachments on an issue \u2014 the work products transition requirements gate on");
+var MIME_BY_EXT = {
+  md: "text/markdown",
+  markdown: "text/markdown",
+  txt: "text/plain",
+  log: "text/plain",
+  html: "text/html",
+  htm: "text/html",
+  css: "text/css",
+  csv: "text/csv",
+  js: "text/javascript",
+  json: "application/json",
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  zip: "application/zip",
+  gz: "application/gzip",
+  mp4: "video/mp4",
+  webm: "video/webm"
+};
+function sniffContentType(path) {
+  const ext = path.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase();
+  return ext && MIME_BY_EXT[ext] || "application/octet-stream";
+}
+function prRefLabel(v) {
+  const path = (v.pr_repo_url ?? "").replace(/^https:\/\/github\.com\//, "");
+  return `${path}#${v.pr_number}`;
+}
+function artifactSummary(a) {
+  const cv = a.current_version;
+  switch (a.artifact_type) {
+    case "file":
+      return `${cv.filename} (${cv.content_type}, ${cv.size_bytes} bytes)`;
+    case "folder":
+      return `${cv.file_count} file${cv.file_count === 1 ? "" : "s"} (${cv.size_bytes} bytes total)`;
+    case "text":
+      return `${cv.filename} (${cv.content_type})`;
+    case "link":
+      return cv.title ? `${cv.title} \u2014 ${cv.url}` : cv.url ?? "";
+    case "pr":
+      return `${prRefLabel(cv)} \u2014 ${cv.pr_repo_url}/pull/${cv.pr_number}`;
+  }
+}
+function walkFolder(dir) {
+  const files = [];
+  const walk = (abs, rel) => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const nextAbs = join3(abs, entry.name);
+      const nextRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(nextAbs, nextRel);
+      else if (entry.isFile()) {
+        files.push({ path: nextRel, contentType: sniffContentType(entry.name), bytes: readFileSync2(nextAbs) });
+      }
+    }
+  };
+  walk(dir, "");
+  return files;
+}
+withCommon(artifactsCmd.command("list <ref>").description("List the artifacts attached to an issue")).action(
+  async (ref, opts) => {
+    const api = client(opts);
+    const issue = await resolveIssue(api, ref);
+    const res = await api.listArtifacts(issue.id);
+    if (opts.json) return printJson(res);
+    if (res.items.length === 0) return console.log("no artifacts attached");
+    table([
+      ["NAME", "TYPE", "VERSION", "FRESH", "SUMMARY", "ATTACHED"],
+      ...res.items.map((a) => [
+        a.name,
+        a.artifact_type,
+        `v${a.current_version.version}`,
+        a.fresh ? "yes" : "no",
+        artifactSummary(a),
+        timestamp(a.current_version.created_at)
+      ])
+    ]);
+  }
+);
+withCommon(
+  artifactsCmd.command("show <ref> <name>").description("Show an artifact with its full version history")
+).action(async (ref, name, opts) => {
+  const api = client(opts);
+  const issue = await resolveIssue(api, ref);
+  const artifact = await api.getArtifact(issue.id, name);
+  if (opts.json) return printJson(artifact);
+  console.log(`${artifact.artifact_type} artifact "${artifact.name}" on ${issue.project_name}/${issue.number}`);
+  if (artifact.description) console.log(artifact.description);
+  console.log(
+    `current: v${artifact.current_version.version} (${artifact.fresh ? "fresh" : "attached before the current state \u2014 reaffirm or attach a new version to satisfy gates"})`
+  );
+  console.log(`summary: ${artifactSummary(artifact)}`);
+  console.log("\nversions:");
+  table(
+    artifact.versions.map((v) => [
+      `  v${v.version}`,
+      timestamp(v.created_at),
+      actorLabel(v.actor),
+      v.reaffirmed_from !== null ? `reaffirmed v${v.reaffirmed_from}` : v.file_count !== null ? `${v.file_count} file${v.file_count === 1 ? "" : "s"}` : v.filename ?? v.url ?? (v.pr_repo_url ? prRefLabel(v) : "")
+    ])
+  );
+  const files = artifact.current_version.files;
+  if (files && files.length > 0) {
+    console.log(`
+files (v${artifact.current_version.version}):`);
+    table(files.map((f) => [`  ${f.path}`, f.content_type, `${f.size_bytes} bytes`]));
+  }
+});
+withCommon(
+  artifactsCmd.command("attach <ref> <name>").description("Attach content to a named artifact slot (creates it, or appends the next version)").option("-f, --file <path>", "upload a file (MIME sniffed from the extension)").option(
+    "--folder <dir>",
+    "snapshot a directory tree as one version (collect locally, attach once; MIME per file sniffed)"
+  ).option("-t, --text <md|@file>", "inline text document: inline Markdown or @file").option("--url <url>", "link: the URL to attach").option("--pr <spec>", "PR reference: owner/repo#N or a GitHub PR URL").option("--content-type <mime>", "declared MIME type (with --file or --text)").option("--filename <name>", "display filename (with --text; defaults to <name>.md)").option("--title <title>", "display title (with --url)").option("-d, --description <text>", "artifact description, shown in lists and launch prompts"),
+  // --url is the link payload here; the API base comes from TINES_API_URL.
+  { baseUrlFlag: false }
+).action(
+  async (ref, name, opts) => {
+    const api = client({ apiKey: opts.apiKey, json: opts.json });
+    const sources = [opts.file, opts.folder, opts.text, opts.url, opts.pr].filter((v) => v !== void 0);
+    if (sources.length !== 1) {
+      die(
+        "pass exactly one content source: --file <path>, --folder <dir>, --text <md|@file>, --url <url>, or --pr <spec>"
+      );
+    }
+    const issue = await resolveIssue(api, ref);
+    let artifact;
+    if (opts.folder !== void 0) {
+      if (!existsSync2(opts.folder) || !statSync(opts.folder).isDirectory()) {
+        die(`--folder needs a directory, got "${opts.folder}"`);
+      }
+      const files = walkFolder(opts.folder);
+      if (files.length === 0) die(`${opts.folder} contains no files to snapshot`);
+      artifact = await api.uploadArtifactFolder(issue.id, name, files);
+      if (opts.description !== void 0) {
+        artifact = await api.putArtifact(issue.id, name, { description: opts.description });
+      }
+    } else if (opts.file !== void 0) {
+      let bytes;
+      try {
+        bytes = readFileSync2(opts.file);
+      } catch (err) {
+        die(`cannot read ${opts.file}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      artifact = await api.uploadArtifactFile(issue.id, name, bytes, {
+        filename: opts.filename ?? basename(opts.file),
+        contentType: opts.contentType ?? sniffContentType(opts.file)
+      });
+      if (opts.description !== void 0) {
+        artifact = await api.putArtifact(issue.id, name, { description: opts.description });
+      }
+    } else if (opts.text !== void 0) {
+      artifact = await api.putArtifact(issue.id, name, {
+        type: "text",
+        content: readBodyValue(opts.text),
+        ...opts.filename !== void 0 ? { filename: opts.filename } : {},
+        ...opts.contentType !== void 0 ? { content_type: opts.contentType } : {},
+        ...opts.description !== void 0 ? { description: opts.description } : {}
+      });
+    } else if (opts.url !== void 0) {
+      artifact = await api.putArtifact(issue.id, name, {
+        type: "link",
+        url: opts.url,
+        ...opts.title !== void 0 ? { title: opts.title } : {},
+        ...opts.description !== void 0 ? { description: opts.description } : {}
+      });
+    } else {
+      const parsed = parsePrSpec(opts.pr);
+      if (!parsed) {
+        die(`--pr takes owner/repo#N or a GitHub PR URL, got "${opts.pr}"`);
+      }
+      artifact = await api.putArtifact(issue.id, name, {
+        type: "pr",
+        pr_repo_url: parsed.repo_url,
+        pr_number: parsed.number,
+        ...opts.description !== void 0 ? { description: opts.description } : {}
+      });
+    }
+    if (opts.json) return printJson(artifact);
+    console.log(
+      `attached "${artifact.name}" v${artifact.current_version.version} (${artifactSummary(artifact)}) to ${issue.project_name}/${issue.number} \u2014 fresh`
+    );
+  }
+);
+withCommon(
+  artifactsCmd.command("reaffirm <ref> <name>").description("Bless the current content as fresh (appends a version reusing the same payload)")
+).action(async (ref, name, opts) => {
+  const api = client(opts);
+  const issue = await resolveIssue(api, ref);
+  const artifact = await api.reaffirmArtifact(issue.id, name);
+  if (opts.json) return printJson(artifact);
+  console.log(
+    `reaffirmed "${artifact.name}" on ${issue.project_name}/${issue.number}: v${artifact.current_version.version} reaffirms v${artifact.current_version.reaffirmed_from} \u2014 fresh as of now`
+  );
+});
+withCommon(
+  artifactsCmd.command("get <ref> <name>").description("Fetch content (current version by default); a link/pr prints its URL").option("--version <n>", "fetch a specific version from the history", (v) => Number.parseInt(v, 10)).option("--out <path>", "write to this file, or into this directory (keeps the stored filename)")
+).action(
+  async (ref, name, opts) => {
+    const api = client(opts);
+    const issue = await resolveIssue(api, ref);
+    const artifact = await api.getArtifact(issue.id, name);
+    const version = opts.version === void 0 ? artifact.current_version : artifact.versions.find((v) => v.version === opts.version);
+    if (!version) {
+      die(
+        `artifact "${name}" has no version ${opts.version} (history: v1\u2013v${artifact.current_version.version})`
+      );
+    }
+    if (artifact.artifact_type === "link" || artifact.artifact_type === "pr") {
+      const url = artifact.artifact_type === "link" ? version.url : `${version.pr_repo_url}/pull/${version.pr_number}`;
+      if (opts.json) return printJson({ url });
+      return console.log(url);
+    }
+    if (artifact.artifact_type === "folder") {
+      if (opts.out === void 0) {
+        die(`artifact "${name}" is a folder \u2014 pass --out <dir> to write its tree`);
+      }
+      if (existsSync2(opts.out) && !statSync(opts.out).isDirectory()) {
+        die(`--out for a folder must be a directory, and "${opts.out}" is a file`);
+      }
+      const files = version.files ?? [];
+      let total = 0;
+      for (const file of files) {
+        const content2 = await api.getArtifactContent(issue.id, name, {
+          version: opts.version,
+          path: file.path
+        });
+        const target2 = join3(opts.out, file.path);
+        mkdirSync3(dirname3(target2), { recursive: true });
+        writeFileSync3(target2, Buffer.from(content2.bytes));
+        total += content2.bytes.byteLength;
+      }
+      return console.log(
+        `wrote ${files.length} file${files.length === 1 ? "" : "s"} (${total} bytes) from "${name}" v${version.version} into ${opts.out}/`
+      );
+    }
+    const content = await api.getArtifactContent(issue.id, name, { version: opts.version });
+    const bytes = Buffer.from(content.bytes);
+    if (opts.out !== void 0) {
+      let target2 = opts.out;
+      if (existsSync2(target2) && statSync(target2).isDirectory()) {
+        target2 = join3(target2, version.filename ?? name);
+      }
+      writeFileSync3(target2, bytes);
+      return console.log(`wrote ${target2} (${bytes.byteLength} bytes, ${content.content_type})`);
+    }
+    if ((content.content_type ?? "").startsWith("text/")) {
+      process.stdout.write(bytes);
+      return;
+    }
+    const target = version.filename ?? name;
+    writeFileSync3(target, bytes);
+    console.log(`wrote ${target} (${bytes.byteLength} bytes, ${content.content_type})`);
+  }
+);
+withCommon(
+  artifactsCmd.command("delete <ref> <name>").description("Delete an artifact \u2014 every version and its stored files (history is not recoverable)")
+).action(async (ref, name, opts) => {
+  const api = client(opts);
+  const issue = await resolveIssue(api, ref);
+  const artifact = await api.getArtifact(issue.id, name);
+  await api.deleteArtifact(issue.id, name);
+  console.log(
+    `deleted ${artifact.artifact_type} artifact "${name}" from ${issue.project_name}/${issue.number} (${artifact.version_count} version${artifact.version_count === 1 ? "" : "s"})`
+  );
+});
 withCommon(
   issues.command("assign <ref> [runner]").description("Pin an issue to a runner (<runner>[:tier]) \u2014 replaces routing rules for it; --clear unpins").option("--clear", "remove the pin")
 ).action(async (ref, runnerSpec, opts) => {
@@ -1840,88 +2258,118 @@ withCommon(
     `seeded global "${AGENT_GUIDELINES_NAME}" (${created.id}) \u2014 it now opens every launch prompt; edit it freely`
   );
 });
-var journal = program.command("journal").description("An issue's stage journal: shared notes for its project + current state");
-async function resolveJournal(api, ref) {
-  const issue = await resolveIssue(api, ref);
+var journal = program.command("journal").description("An issue's stage journal: shared notes for its project + the stage your run was launched in");
+var STATE_FLAG_HELP = "target this state's journal instead of your run's launch stage (options go BEFORE <ref>)";
+async function journalItemAt(api, scope) {
   const { items } = await api.listContext({
     kind: "prompt",
-    project: issue.project_id,
-    state: issue.state.id,
+    project: scope.project_id ?? void 0,
+    state: scope.workflow_state_id ?? void 0,
     exact: true,
     limit: 100
   });
-  return { issue, item: items.find((i) => i.name === JOURNAL_NAME) ?? null };
+  return items.find((i) => i.name === JOURNAL_NAME) ?? null;
+}
+function stateScope(issue, state, workflow) {
+  return {
+    project_id: issue.project_id,
+    project_name: issue.project_name,
+    workflow_state_id: state.id,
+    workflow_state_name: state.name,
+    workflow_id: workflow.id,
+    workflow_name: workflow.name,
+    issue_id: null,
+    issue_ref: null,
+    label: `project ${issue.project_name} \xB7 state ${state.name}`
+  };
+}
+async function resolveJournal(api, ref, stateRef) {
+  const issue = await resolveIssue(api, ref);
+  if (stateRef !== void 0) {
+    const { workflow, state } = await resolveStateFlag(api, stateRef);
+    const scope = stateScope(issue, state, workflow);
+    return { issue, scope, note: null, item: await journalItemAt(api, scope) };
+  }
+  try {
+    const { scope, note, item } = await api.getIssueJournal(issue.id);
+    return { issue, scope, note, item };
+  } catch (err) {
+    if (!(err instanceof ApiError) || err.status !== 404) throw err;
+    const scope = stateScope(issue, issue.state, issue.workflow);
+    return { issue, scope, note: null, item: await journalItemAt(api, scope) };
+  }
+}
+function printNote(note) {
+  if (note) console.error(`note: ${note}`);
 }
 withCommon(
-  journal.command("show <ref>").description("Print the journal for the issue's project and current state")
+  journal.command("show <ref>").description("Print the journal for the stage your run was launched in").option("--state <workflow>/<state>", STATE_FLAG_HELP)
 ).action(async (ref, opts) => {
   const api = client(opts);
-  const { issue, item } = await resolveJournal(api, ref);
+  const { issue, scope, note, item } = await resolveJournal(api, ref, opts.state);
+  printNote(note);
   if (!item) {
     die(
-      `no journal exists yet for project ${issue.project_name} \xB7 state ${issue.state.name}
+      `no journal exists yet for ${scope.label}
 start one: tines journal append ${issue.project_name}/${issue.number} "- <date>: <lesson>"`
     );
   }
   const full = await api.getContextItem(item.id);
   if (opts.json) return printJson(full);
-  console.log(`journal for project ${issue.project_name} \xB7 state ${issue.state.name}  (v${full.version})`);
+  console.log(`journal for ${scope.label}  (v${full.version})`);
   console.log("");
   console.log(full.body ?? "");
 });
 withCommon(
-  journal.command("append <ref> <markdown>").description("Append a lesson (creates the journal on first use)").passThroughOptions()
-).action(async (ref, markdown, opts, command) => {
-  if (helpGuard(command, markdown)) return;
-  const api = client(opts);
-  const { issue, item } = await resolveJournal(api, ref);
-  const scopeLabel = `project ${issue.project_name} \xB7 state ${issue.state.name}`;
-  if (item) {
-    const updated = await api.appendContextItem(item.id, { text: markdown });
-    if (opts.json) return printJson(updated);
-    return console.log(`appended to the ${scopeLabel} journal (now v${updated.version})`);
-  }
-  try {
-    const created = await api.createContextItem({
-      kind: "prompt",
-      name: JOURNAL_NAME,
-      project_id: issue.project_id,
-      workflow_state_id: issue.state.id,
-      body: markdown.trim()
-    });
-    if (opts.json) return printJson(created);
-    console.log(`started the ${scopeLabel} journal (${created.id})`);
-  } catch (err) {
-    if (!(err instanceof ApiError) || err.code !== "duplicate_context_name") throw err;
-    const { item: fresh } = await resolveJournal(api, ref);
-    if (!fresh) throw err;
-    const updated = await api.appendContextItem(fresh.id, { text: markdown });
-    if (opts.json) return printJson(updated);
-    console.log(`appended to the ${scopeLabel} journal (now v${updated.version})`);
+  journal.command("append <ref> <markdown>").description("Append a lesson (creates the journal on first use)").option("--state <workflow>/<state>", STATE_FLAG_HELP).passThroughOptions()
+).action(
+  async (ref, markdown, opts, command) => {
+    if (helpGuard(command, markdown)) return;
+    const api = client(opts);
+    const { scope, note, item } = await resolveJournal(api, ref, opts.state);
+    printNote(note);
+    if (item) {
+      const updated = await api.appendContextItem(item.id, { text: markdown });
+      if (opts.json) return printJson(updated);
+      return console.log(`appended to the ${scope.label} journal (now v${updated.version})`);
+    }
+    try {
+      const created = await api.createContextItem({
+        kind: "prompt",
+        name: JOURNAL_NAME,
+        project_id: scope.project_id ?? void 0,
+        workflow_state_id: scope.workflow_state_id ?? void 0,
+        body: markdown.trim()
+      });
+      if (opts.json) return printJson(created);
+      console.log(`started the ${scope.label} journal (${created.id})`);
+    } catch (err) {
+      if (!(err instanceof ApiError) || err.code !== "duplicate_context_name") throw err;
+      const { item: fresh } = await resolveJournal(api, ref, opts.state);
+      if (!fresh) throw err;
+      const updated = await api.appendContextItem(fresh.id, { text: markdown });
+      if (opts.json) return printJson(updated);
+      console.log(`appended to the ${scope.label} journal (now v${updated.version})`);
+    }
   }
-});
+);
 withCommon(
-  journal.command("rewrite <ref>").description("Replace the journal body (to fix or prune entries) \u2014 version-checked").requiredOption("--body <md>", "the full new body: inline Markdown or @file").requiredOption(
+  journal.command("rewrite <ref>").description("Replace the journal body (to fix or prune entries) \u2014 version-checked").option("--state <workflow>/<state>", STATE_FLAG_HELP).requiredOption("--body <md>", "the full new body: inline Markdown or @file").requiredOption(
     "--expect-version <n>",
     "the version being replaced (from the prompt or journal show)",
     (v) => Number.parseInt(v, 10)
   )
 ).action(async (ref, opts) => {
   const api = client(opts);
-  const { issue, item } = await resolveJournal(api, ref);
-  if (!item) {
-    die(
-      `no journal exists yet for project ${issue.project_name} \xB7 state ${issue.state.name}; nothing to rewrite`
-    );
-  }
+  const { scope, note, item } = await resolveJournal(api, ref, opts.state);
+  printNote(note);
+  if (!item) die(`no journal exists yet for ${scope.label}; nothing to rewrite`);
   const updated = await api.updateContextItem(item.id, {
     body: readBodyValue(opts.body),
     expected_version: opts.expectVersion
   });
   if (opts.json) return printJson(updated);
-  console.log(
-    `rewrote the project ${issue.project_name} \xB7 state ${issue.state.name} journal (now v${updated.version})`
-  );
+  console.log(`rewrote the ${scope.label} journal (now v${updated.version})`);
 });
 var schedules = program.command("schedules").description("Manage scheduled tasks (addressed as <project>/<name>)");
 function scheduleRef(s) {
@@ -2124,6 +2572,125 @@ withCommon(runners.command("show <name>").description("Show a runner")).action(
     }
     const harness = runner.config.harness;
     if (typeof harness === "string") console.log(`harness: ${harness}`);
+    if (runner.type !== "local") {
+      console.log(`api key: ${runner.has_api_key ? "set (write-only)" : "missing"}`);
+    }
+    if (runner.budget) {
+      const b = runner.budget;
+      const parts = [];
+      if (b.max_run_cost_usd !== void 0) parts.push(`$${b.max_run_cost_usd}/run`);
+      if (b.max_run_tokens !== void 0) parts.push(`${b.max_run_tokens.toLocaleString()} tok/run`);
+      if (b.daily_usd !== void 0) parts.push(`$${b.daily_usd}/day`);
+      if (b.daily_tokens !== void 0) parts.push(`${b.daily_tokens.toLocaleString()} tok/day`);
+      if (parts.length > 0) console.log(`budget: ${parts.join("  ")}`);
+    }
+    printTierTable(runner);
+  }
+);
+function printTierTable(runner) {
+  if (!runner.tier_models && !runner.tiers) {
+    console.log("tiers: don't apply to this runner (fixed configuration)");
+    return;
+  }
+  console.log("tiers:");
+  for (const tier of MODEL_TIERS) {
+    const override = runner.tiers?.[tier];
+    const builtin = runner.tier_models?.[tier] ?? null;
+    const model = override?.model ?? builtin ?? "(unknown)";
+    const source = override ? "override" : "built-in";
+    const stale = isStaleTierOverride(builtin, override?.model);
+    const marks = [
+      tier === runner.default_tier ? "default" : null,
+      override?.effort ? `effort ${override.effort}` : null,
+      stale ? `stale \u2014 built-in is now ${builtin}` : null
+    ].filter(Boolean);
+    console.log(`  ${tier}: ${model}  [${source}]${marks.length > 0 ? `  (${marks.join(", ")})` : ""}`);
+  }
+}
+withCommon(
+  runners.command("tiers <name>").description("Show or edit a runner's tier\u2192model mapping").option("--default <tier>", "set the default tier (used by targets without an explicit tier)").option("--set <tier=model...>", "override a tier with an exact model id (repeatable)").option("--unset <tier...>", "drop an override, falling back to the built-in (repeatable)")
+).action(
+  async (ref, opts) => {
+    const api = client(opts);
+    const runner = await resolveRunner(api, ref);
+    const patch = {};
+    if (opts.default !== void 0) {
+      if (!MODEL_TIERS.includes(opts.default)) {
+        die(`unknown tier "${opts.default}" (tiers: ${MODEL_TIERS.join(", ")})`);
+      }
+      patch.default_tier = opts.default;
+    }
+    if (opts.set?.length || opts.unset?.length) {
+      const tiers = {
+        ...runner.tiers ?? {}
+      };
+      for (const entry of opts.set ?? []) {
+        const eq = entry.indexOf("=");
+        if (eq === -1) die(`--set takes <tier>=<model-id>, got "${entry}"`);
+        const tier = entry.slice(0, eq);
+        const model = entry.slice(eq + 1);
+        if (!MODEL_TIERS.includes(tier)) {
+          die(`unknown tier "${tier}" (tiers: ${MODEL_TIERS.join(", ")})`);
+        }
+        if (!model) die(`--set ${tier}= needs a model id`);
+        tiers[tier] = { ...tiers[tier], model };
+      }
+      for (const tier of opts.unset ?? []) {
+        if (!MODEL_TIERS.includes(tier)) {
+          die(`unknown tier "${tier}" (tiers: ${MODEL_TIERS.join(", ")})`);
+        }
+        delete tiers[tier];
+      }
+      patch.tiers = Object.keys(tiers).length > 0 ? tiers : null;
+    }
+    const updated = Object.keys(patch).length > 0 ? await api.updateRunner(runner.id, patch) : runner;
+    if (opts.json) return printJson(updated);
+    console.log(`${updated.name}  (${updated.type})  default tier: ${updated.default_tier}`);
+    printTierTable(updated);
+    if (Object.keys(patch).length > 0) {
+      console.log("changes apply at the next launch; running work is untouched.");
+    }
+  }
+);
+withCommon(
+  runners.command("budget <name>").description("Set or clear a runner's money limits (per-run caps enforce now; daily limits arrive with the budgets milestone)").option("--max-run-usd <n>", "hard per-run cost cap (platform-enforced on Claude runners)").option("--max-run-tokens <n>", "hard per-run token cap (input + output)").option("--daily-usd <n>", "daily USD limit (stored now, enforced by the budgets milestone)").option("--daily-tokens <n>", "daily token limit (stored now, enforced by the budgets milestone)").option("--clear", "remove all limits")
+).action(
+  async (ref, opts) => {
+    const api = client(opts);
+    const runner = await resolveRunner(api, ref);
+    const flags = [opts.maxRunUsd, opts.maxRunTokens, opts.dailyUsd, opts.dailyTokens].some(
+      (v) => v !== void 0
+    );
+    if (opts.clear && flags) die("--clear cannot be combined with limit flags");
+    let updated = runner;
+    if (opts.clear) {
+      updated = await api.updateRunner(runner.id, { budget: null });
+    } else if (flags) {
+      const num = (value, flag) => {
+        const n = Number(value);
+        if (!Number.isFinite(n) || n <= 0) die(`${flag} must be a positive number, got "${value}"`);
+        return n;
+      };
+      updated = await api.updateRunner(runner.id, {
+        budget: {
+          ...runner.budget ?? {},
+          ...opts.maxRunUsd !== void 0 ? { max_run_cost_usd: num(opts.maxRunUsd, "--max-run-usd") } : {},
+          ...opts.maxRunTokens !== void 0 ? { max_run_tokens: num(opts.maxRunTokens, "--max-run-tokens") } : {},
+          ...opts.dailyUsd !== void 0 ? { daily_usd: num(opts.dailyUsd, "--daily-usd") } : {},
+          ...opts.dailyTokens !== void 0 ? { daily_tokens: num(opts.dailyTokens, "--daily-tokens") } : {}
+        }
+      });
+    }
+    if (opts.json) return printJson(updated);
+    const b = updated.budget;
+    if (!b) return console.log(`no limits on "${updated.name}"`);
+    console.log(`limits on "${updated.name}":`);
+    if (b.max_run_cost_usd !== void 0) console.log(`  $${b.max_run_cost_usd} per run`);
+    if (b.max_run_tokens !== void 0) console.log(`  ${b.max_run_tokens.toLocaleString()} tokens per run`);
+    if (b.daily_usd !== void 0) console.log(`  $${b.daily_usd} per day (enforced by the budgets milestone)`);
+    if (b.daily_tokens !== void 0) {
+      console.log(`  ${b.daily_tokens.toLocaleString()} tokens per day (enforced by the budgets milestone)`);
+    }
   }
 );
 withCommon(
@@ -2204,6 +2771,14 @@ withCommon(
   }
 );
 var runsCmd = program.command("runs").description("Agent runs: attempts at issues by runners");
+function runCostLabel(run) {
+  const usage = run.usage;
+  if (!usage) return "\u2014";
+  if (usage.cost_usd !== void 0) return `$${usage.cost_usd.toFixed(2)}`;
+  if (usage.cost_source === "none") return "unreported";
+  const tokens = (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0);
+  return tokens > 0 ? `${tokens.toLocaleString()} tok` : "\u2014";
+}
 function runRow(run) {
   return [
     run.id,
@@ -2212,6 +2787,7 @@ function runRow(run) {
     `${run.tier}${run.model ? ` (${run.model})` : ""}`,
     run.status,
     runDurationLabel(run),
+    runCostLabel(run),
     timestamp(run.created_at)
   ];
 }
@@ -2230,7 +2806,7 @@ withList(
   });
   printList(res, opts, (items) => {
     if (items.length === 0) return console.log(opts.active ? "no active runs" : "no runs");
-    table([["ID", "ISSUE", "RUNNER", "TIER", "STATUS", "DURATION", "CREATED"], ...items.map(runRow)]);
+    table([["ID", "ISSUE", "RUNNER", "TIER", "STATUS", "DURATION", "COST", "CREATED"], ...items.map(runRow)]);
   });
 });
 withCommon(
@@ -2248,6 +2824,16 @@ withCommon(
   console.log(
     `created: ${timestamp(run.created_at)}  started: ${run.started_at ? timestamp(run.started_at) : "\u2014"}  ended: ${run.ended_at ? timestamp(run.ended_at) : "\u2014"}  duration: ${runDurationLabel(run)}`
   );
+  if (run.usage) {
+    const u = run.usage;
+    const parts = [];
+    if (u.input_tokens !== void 0 || u.output_tokens !== void 0) {
+      parts.push(`${(u.input_tokens ?? 0).toLocaleString()} in / ${(u.output_tokens ?? 0).toLocaleString()} out tokens`);
+    }
+    if (u.cost_usd !== void 0) parts.push(`$${u.cost_usd.toFixed(2)}`);
+    if (u.cost_source) parts.push(`(${u.cost_source === "provider" ? "provider-reported" : u.cost_source})`);
+    if (parts.length > 0) console.log(`usage: ${parts.join("  ")}`);
+  }
   if (run.provider_session_id) console.log(`provider session: ${run.provider_session_id}`);
   if (run.provider_url) console.log(`provider console: ${run.provider_url}`);
   if (run.error) console.log(`error: ${run.error}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tines",
-  "version": "0.0.1",
+  "version": "0.0.76",
   "description": "CLI for Tines, an orchestration layer for AI agents",
   "repository": {
     "type": "git",