tracksiy 0.1.1 → 0.3.0

package/README.md

@@ -128,10 +128,15 @@ Labels: `bug`, `feature`, `question`, `blocker`. `npx tracksiy support` prints t
 | `performance` | Is this project slow, and did it get slower? Transactions compared with the previous window, plus uptime. | read | `performance` |
 | `issues list` | Recent issues of a project, newest activity first, with the frames that matter inlined. | read | `issues_list` |
 | `issues view <id>` | One issue in enough depth to act on: latest event, stack frames, tags, recent volume. | read | `issues_view` |
-| `issues resolve <ids...>` | Mark issues resolved. A new event on a resolved issue reopens it as a regression. | write | `issues_resolve` |
-| `issues ignore <ids...>` | Mark issues ignored: they stop alerting until unignored. | write | `issues_ignore` |
+| `issues resolve <ids...>` | Mark issues resolved, optionally fixed in a release so old clients do not reopen them. Records why. | write | `issues_resolve` |
+| `issues ignore <ids...>` | Mark issues ignored: they stop alerting until unignored. Records why. | write | `issues_ignore` |
 | `issues unresolve <ids...>` | Reopen issues. | write | `issues_unresolve` |
 | `issues bulk-status` | Change the status of every issue matching a filter. Dry run unless --apply. | write | `issues_bulk_status` |
+| `issues comment <id>` | Leave a comment on an issue for the next agent or human: what you found, what you tried. | write | `issues_comment` |
+| `issues activity <id>` | Who did what to an issue and why: resolutions (and in which release), regressions, comments, claims. | read | `issues_activity` |
+| `issues verify-fixed <id>` | Did the fix hold? Judged by the fix release's own traffic: fixed, regressed or undetermined. Exit 10 unless fixed. | read | `issues_verify_fixed` |
+| `issues claim <id>` | Take a lease on an issue so no other agent works on it meanwhile. Lapses on its own. | write | `issues_claim` |
+| `issues unclaim <id>` | Give back your lease on an issue. | write | `issues_unclaim` |
 | `projects create <name>` | Everything a new app needs in one idempotent call: the project, an ingest key per surface, an upload token, and the next steps. | write | `projects_create` |
 | `projects verify` | Did the integration actually work? Checks events, releases, environments, source maps, privacy and alerting. Exit 10 if not. | read | `projects_verify` |
 | `onboarding` | What to know before integrating an app. No token needed. | read | `onboarding` |

package/dist/tracksiy.mjs

@@ -4,7 +4,7 @@
 import { readFileSync as readFileSync2 } from "node:fs";
 
 // src/version.ts
-var VERSION = true ? "0.1.1" : "0.0.0-dev";
+var VERSION = true ? "0.3.0" : "0.0.0-dev";
 var USER_AGENT = `tracksiy-cli/${VERSION} (node ${process.versions.node}; ${process.platform})`;
 
 // src/core/errors.ts
@@ -115,6 +115,7 @@ var Api = class {
     const headers = { "User-Agent": USER_AGENT, Accept: "application/json" };
     const useAuth = opts.auth !== false;
     if (useAuth && this.opts.token) headers.Authorization = `Bearer ${this.opts.token}`;
+    if (this.opts.agent) headers["X-Tracksiy-Agent"] = this.opts.agent;
     let body;
     if (opts.form) body = opts.form;
     else if (opts.body !== void 0) {
@@ -375,6 +376,8 @@ function resolveConfig(globals, env = process.env, cwd = process.cwd()) {
     verbose: Boolean(globals.verbose),
     quiet: Boolean(globals.quiet)
   };
+  const agent = (globals.as ?? env.TRACKSIY_AGENT ?? "").trim();
+  if (agent) out.agent = agent.slice(0, 100);
   if (pf) out.projectFile = pf.path;
   if (globals.token) [out.token, out.tokenSource] = [globals.token, "--token"];
   else if (env.TRACKSIY_TOKEN) [out.token, out.tokenSource] = [env.TRACKSIY_TOKEN, "TRACKSIY_TOKEN"];
@@ -641,6 +644,7 @@ function missingToken(url) {
 var auth_default = [login, status, logout];
 
 // src/commands/_util.ts
+import { readFileSync as readFileSync3 } from "node:fs";
 async function projectPath(ctx, suffix = "") {
   const { org, project: project2 } = await ctx.project();
   return `projects/${seg(org)}/${seg(project2)}${suffix ? `/${suffix}` : ""}`;
@@ -679,6 +683,26 @@ function rate(value, flag) {
 function compact(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
 }
+function textArg(value, flag) {
+  if (value === void 0 || value === null) return void 0;
+  const raw = String(value);
+  if (raw === "-") return readFileSync3(0, "utf8");
+  if (raw.startsWith("@")) {
+    try {
+      return readFileSync3(raw.slice(1), "utf8");
+    } catch (err) {
+      throw usageError("bad_value", `--${flag}: cannot read ${raw.slice(1)}: ${err.message}`);
+    }
+  }
+  return raw;
+}
+function duration(value, flag) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const s = String(value).trim();
+  const m = /^(\d+)\s*([smhdw])?$/.exec(s);
+  if (!m) throw usageError("bad_value", `--${flag} expects a duration like 30m / 2h / 1d, got ${JSON.stringify(s)}`);
+  return Number(m[1]) * (m[2] ? UNITS[m[2]] : 1);
+}
 
 // src/commands/fleet.ts
 var orgs = {
@@ -920,6 +944,26 @@ var FILTERS = {
   "first-seen-since": { type: "string", value: TIME, description: "First seen at or after this: new issues only." },
   "first-seen-until": { type: "string", value: TIME, description: "First seen before this." }
 };
+var WHY = {
+  reason: { type: "string", enum: ["fixed", "duplicate", "third_party", "expected", "wont_fix"], description: "Why, recorded on the issue's activity log." },
+  note: { type: "string", value: "<md|@file|->", description: "A note for the next agent (markdown), kept on the activity log." },
+  ref: { type: "string", value: "<sha|url>", description: "The evidence: a commit, PR or URL." }
+};
+var FIXED_IN = {
+  "in-release": { type: "string", value: "<version>", description: "Fixed in this release: events from older releases count as stale, not as a regression. Must exist (releases declare)." },
+  "in-commit": { type: "string", value: "<sha>", description: "Fixed in the release that carries this commit (its ref, or a version ending @<sha>); bound when that release appears." },
+  "in-next-release": { type: "boolean", description: "Fixed in whatever is released next: only newer releases can reopen it." }
+};
+function whyBody(input) {
+  return compact({
+    inRelease: input.inRelease,
+    inCommit: input.inCommit,
+    inNextRelease: input.inNextRelease || void 0,
+    reason: input.reason,
+    note: textArg(input.note, "note"),
+    ref: input.ref
+  });
+}
 function filterQuery(input) {
   return compact({
     status: input.status,
@@ -952,14 +996,17 @@ var list = {
     ...FILTERS,
     sort: { type: "string", enum: ["lastSeen", "firstSeen", "count"], description: "Order. Default lastSeen." },
     limit: { type: "integer", value: "<n>", description: "How many issues (server default 25)." },
-    frames: { type: "integer", value: "<n>", description: "In-app stack frames inlined per issue (default 3, 0 for none)." }
+    frames: { type: "integer", value: "<n>", description: "In-app stack frames inlined per issue (default 3, 0 for none)." },
+    unclaimed: { type: "boolean", description: "Only issues nobody holds a live claim on: what you can pick up." },
+    "claimed-by": { type: "string", value: "<handle>", description: "Only issues claimed by this handle." }
   },
   examples: [
     { command: "tracksiy issues list --since 24h", description: "Unresolved issues seen in the last day." },
+    { command: "tracksiy issues list --unclaimed --limit 5", description: "Five issues no other agent is working on." },
     { command: "tracksiy issues list --status regressed --select issues.id,issues.title", description: "Only regressions, only ids and titles." },
     { command: "tracksiy issues list --first-seen-since 2h --environment production", description: "What is new in production." }
   ],
-  output: "{project, issueCount, total, hasMore, issues:[{id, shortId, title, culprit, level, status, count, firstSeen, lastSeen, regressedAt, timesRegressed, permalink, frames?}]}",
+  output: "{project, issueCount, total, hasMore, issues:[{id, shortId, title, culprit, level, status, count, firstSeen, lastSeen, regressedAt, timesRegressed, resolution?, staleEvents, claimedBy?, claimedUntil?, permalink, frames?}]}",
   text: (d) => `${d.issueCount ?? d.issues?.length ?? 0} of ${d.total ?? "?"} issues${d.hasMore ? " (more: raise --limit)" : ""}
 ${issueRows(d.issues)}`,
   async run(ctx) {
@@ -967,7 +1014,9 @@ ${issueRows(d.issues)}`,
       ...filterQuery(ctx.input),
       sort: ctx.input.sort,
       limit: ctx.input.limit,
-      frames: ctx.input.frames
+      frames: ctx.input.frames,
+      unclaimed: ctx.input.unclaimed || void 0,
+      claimedBy: ctx.input.claimedBy
     });
   }
 };
@@ -980,7 +1029,7 @@ var view = {
   args: [{ name: "id", required: true, description: "Issue id (numeric, from `issues list`)." }],
   flags: { frames: { type: "integer", value: "<n>", description: "How many frames to include." } },
   examples: [{ command: "tracksiy issues view 4812", description: "Everything needed to start fixing issue 4812." }],
-  output: "{id, title, culprit, level, status, count, firstSeen, lastSeen, latestEvent{release, environment, exceptionType, exceptionValue, contexts}, frames[{filename, function, lineno, contextLine, inApp}], tags[], eventsLast24h, eventsLast7d, permalink}",
+  output: "{id, title, culprit, level, status, count, firstSeen, lastSeen, resolution?, staleEvents, claimedBy?, latestEvent{release, environment, exceptionType, exceptionValue, contexts}, frames[{filename, function, lineno, contextLine, inApp}], tags[], eventsLast24h, eventsLast7d, activity[], recentComments[], permalink}",
   text: (d) => {
     const head = kv(d, ["id", "shortId", "title", "culprit", "level", "status", "count", "eventsLast24h", "eventsLast7d", "firstSeen", "lastSeen", "regressedAt", "permalink"]);
     const ev = d.latestEvent ? `
@@ -988,15 +1037,22 @@ latest event:
 ${kv(d.latestEvent, ["release", "environment", "exceptionType", "exceptionValue", "transaction", "platform"]).replace(/^/gm, "  ")}` : "";
     const frames = (d.frames ?? []).map((f) => `  ${f.inApp ? "*" : " "} ${f.filename ?? f.module ?? "?"}:${f.lineno ?? "?"} in ${f.function ?? "?"}${f.contextLine ? `
       ${String(f.contextLine).trim()}` : ""}`).join("\n");
-    return `${head}${ev}${frames ? `
+    const res = d.resolution ? `
+resolved ${d.resolution.type.replace(/_/g, " ")}: ${d.resolution.release ?? d.resolution.commit ?? "-"}${d.resolution.pending ? " (pending)" : ""}; ${d.staleEvents ?? 0} stale event(s)` : "";
+    const claim2 = d.claimedBy ? `
+claimed by ${d.claimedBy} until ${d.claimedUntil}` : "";
+    const act = (d.activity ?? []).slice(0, 5).map((a) => `  ${ago(a.at)} ${a.action}${a.reason ? ` (${a.reason})` : ""} by ${a.actor ?? a.user ?? a.via}${a.note ? `: ${String(a.note).split("\n")[0].slice(0, 100)}` : ""}`).join("\n");
+    return `${head}${res}${claim2}${ev}${frames ? `
 frames (* = in app):
-${frames}` : ""}`;
+${frames}` : ""}${act ? `
+activity:
+${act}` : ""}`;
   },
   async run(ctx) {
     return ctx.api.get(await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}`), { frames: ctx.input.frames });
   }
 };
-function statusCommand(name, status2, summary) {
+function statusCommand(name, status2, summary, examples) {
   return {
     path: ["issues", name],
     summary,
@@ -1005,19 +1061,139 @@ function statusCommand(name, status2, summary) {
     idempotent: true,
     endpoint: { method: "POST", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/status" },
     args: [{ name: "ids", required: true, variadic: true, description: "One or more issue ids." }],
-    examples: [{ command: `tracksiy issues ${name} 4812 4813`, description: `Mark two issues ${status2}.` }],
-    output: "One id: the issue's new state. Several: {matched, changed, ids, dryRun:false}.",
+    flags: name === "resolve" ? { ...FIXED_IN, ...WHY } : { ...WHY },
+    examples,
+    output: "One id: the issue's new state with changed, requested, applied. Several: {matched, updated, alreadyInStatus, resolution, dryRun:false}.",
     async run(ctx) {
       const ids = ctx.input.ids;
       for (const id of ids) if (!/^\d+$/.test(id)) throw usageError("bad_value", `Issue ids are numeric; got ${JSON.stringify(id)}`);
-      if (ids.length === 1) return ctx.api.send("POST", await projectPath(ctx, `issues/${ids[0]}/status`), { status: status2 });
-      return ctx.api.send("POST", await projectPath(ctx, "issues/status"), { status: status2, ids, dryRun: false });
+      const why = whyBody(ctx.input);
+      if (ids.length === 1) return ctx.api.send("POST", await projectPath(ctx, `issues/${ids[0]}/status`), { status: status2, ...why });
+      return ctx.api.send("POST", await projectPath(ctx, "issues/status"), { status: status2, ids, dryRun: false, ...why });
     }
   };
 }
-var resolve2 = statusCommand("resolve", "resolved", "Mark issues resolved. A new event on a resolved issue reopens it as a regression.");
-var ignore = statusCommand("ignore", "ignored", "Mark issues ignored: they stop alerting until unignored.");
-var unresolve = statusCommand("unresolve", "unresolved", "Reopen issues.");
+var resolve2 = statusCommand(
+  "resolve",
+  "resolved",
+  "Mark issues resolved, optionally fixed in a release so old clients do not reopen them. Records why.",
+  [
+    { command: "tracksiy issues resolve 4812 --in-release web@$(git rev-parse HEAD) --reason fixed --ref $(git rev-parse HEAD)", description: "Fixed in this deploy; old bundles count as stale." },
+    { command: "tracksiy issues resolve 4812 --in-next-release --note @why.md", description: "Fixed in whatever ships next, with the reasoning." },
+    { command: "tracksiy issues resolve 5562 --reason third_party --note 'WebView injects addEL_hook'", description: "Not our code: closed with the reason on record." }
+  ]
+);
+var ignore = statusCommand("ignore", "ignored", "Mark issues ignored: they stop alerting until unignored. Records why.", [
+  { command: "tracksiy issues ignore 4812 --reason expected --note 'Bots hitting a removed URL'", description: "Ignore, and say why for the next agent." }
+]);
+var unresolve = statusCommand("unresolve", "unresolved", "Reopen issues.", [{ command: "tracksiy issues unresolve 4812 --note 'Came back on Android'", description: "Reopen with a note." }]);
+var comment = {
+  path: ["issues", "comment"],
+  summary: "Leave a comment on an issue for the next agent or human: what you found, what you tried.",
+  context: "project",
+  effect: "write",
+  endpoint: { method: "POST", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/comments" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: { text: { type: "string", required: true, value: "<md|@file|->", description: "The comment (markdown). @file reads a file, - reads stdin." } },
+  examples: [{ command: "tracksiy issues comment 4812 --text @findings.md", description: "Attach what you found." }],
+  output: "{id, created, user, text}",
+  async run(ctx) {
+    return ctx.api.send("POST", await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/comments`), { text: textArg(ctx.input.text, "text") });
+  }
+};
+var activity = {
+  path: ["issues", "activity"],
+  summary: "Who did what to an issue and why: resolutions (and in which release), regressions, comments, claims.",
+  context: "project",
+  effect: "read",
+  endpoint: { method: "GET", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/activity" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: { limit: { type: "integer", value: "<n>", description: "How many entries (1..500, default 100)." } },
+  examples: [{ command: "tracksiy issues activity 4812", description: "The issue's history, newest first." }],
+  output: "{issue, activity:[{at, action, via, actor, user, reason, note, ref, data}], comments:[{id, created, user, text}]}",
+  text: (d) => table(d.activity ?? [], [
+    ["when", (r) => ago(r.at)],
+    "action",
+    ["by", (r) => r.actor ?? r.user ?? r.via],
+    ["reason", (r) => r.reason ?? ""],
+    ["note", (r) => String(r.note ?? (r.data?.release ? `release ${r.data.release}` : "")).split("\n")[0].slice(0, 80)]
+  ]),
+  async run(ctx) {
+    return ctx.api.get(await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/activity`), { limit: ctx.input.limit });
+  }
+};
+var verifyFixed = {
+  path: ["issues", "verify-fixed"],
+  summary: "Did the fix hold? Judged by the fix release's own traffic: fixed, regressed or undetermined. Exit 10 unless fixed.",
+  description: "regressed: the issue has an event from the fix release or a newer one. undetermined: the fix release has had too little traffic (--min-traffic), or the issue's old rate predicts fewer than 3 occurrences in that traffic. fixed otherwise. The fix release defaults to the one the issue was resolved in. --wait polls until the verdict is not undetermined.",
+  context: "project",
+  effect: "read",
+  endpoint: { method: "GET", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/verify" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: {
+    release: { type: "string", value: "<version>", description: "The fix release. Default: the one it was resolved in." },
+    "min-traffic": { type: "integer", value: "<n>", description: "Transactions + errors + sessions from the fix release needed before silence counts (default 100)." },
+    wait: { type: "integer", value: "<seconds>", description: "Poll every 30 s until fixed or regressed, up to this long." }
+  },
+  examples: [
+    { command: "tracksiy issues verify-fixed 4812", description: "Verdict now." },
+    { command: "tracksiy issues verify-fixed 4812 --wait 1800", description: "In a deploy script: wait up to 30 min for enough traffic." }
+  ],
+  output: "{verdict, reason, release, since, eventsSince, staleEvents, traffic{transactions, errors, sessions, total}, baselinePer1000, expectedEvents, latestEvent?}",
+  text: (d) => kv(d, ["verdict", "reason", "release", "since", "eventsSince", "staleEvents", "expectedEvents"]) + `
+traffic: ${d.traffic?.total ?? 0} (${d.traffic?.transactions ?? 0} transactions, ${d.traffic?.errors ?? 0} errors, ${d.traffic?.sessions ?? 0} sessions)`,
+  async run(ctx) {
+    const path = await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/verify`);
+    const query = { release: ctx.input.release, minTraffic: ctx.input.minTraffic };
+    const deadline = Date.now() + (ctx.input.wait ?? 0) * 1e3;
+    let data = await ctx.api.get(path, query);
+    while (data?.verdict === "undetermined" && Date.now() + 3e4 <= deadline) {
+      ctx.log(`undetermined: ${data.reason} -- checking again in 30 s`);
+      await new Promise((r) => setTimeout(r, 3e4));
+      data = await ctx.api.get(path, query);
+    }
+    if (data?.verdict !== "fixed") throw new CheckFailed(`${data?.verdict ?? "unknown"}: ${data?.reason ?? ""}`, data, data?.verdict === "regressed" ? "Reopened by its own release: look at latestEvent." : "Wait for traffic (--wait), or lower --min-traffic.");
+    return data;
+  }
+};
+var claim = {
+  path: ["issues", "claim"],
+  summary: "Take a lease on an issue so no other agent works on it meanwhile. Lapses on its own.",
+  description: "The holder is your handle: --as, TRACKSIY_AGENT, else the token's label. Claiming what you hold extends it. Someone else's live claim is an error naming them, unless --force. Resolving or ignoring releases it.",
+  context: "project",
+  effect: "write",
+  endpoint: { method: "POST", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/claim" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: {
+    for: { type: "string", value: "<30m|2h|1d>", description: "Lease length (60 s to 7 days). Default 2h." },
+    force: { type: "boolean", description: "Take it from another live holder." }
+  },
+  examples: [{ command: "TRACKSIY_AGENT=logistivo-app tracksiy issues claim 4812 --for 2h", description: "Work on 4812 for two hours." }],
+  output: "The issue with claimedBy, claimedUntil, changed, previousClaimedBy.",
+  async run(ctx) {
+    return ctx.api.send(
+      "POST",
+      await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/claim`),
+      compact({ seconds: duration(ctx.input.for, "for"), force: ctx.input.force || void 0 })
+    );
+  }
+};
+var unclaim = {
+  path: ["issues", "unclaim"],
+  summary: "Give back your lease on an issue.",
+  context: "project",
+  effect: "write",
+  idempotent: true,
+  endpoint: { method: "DELETE", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/claim" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: { force: { type: "boolean", description: "Release someone else's claim." } },
+  examples: [{ command: "tracksiy issues unclaim 4812", description: "Done, or giving up: let others take it." }],
+  output: "The issue with changed and previousClaimedBy.",
+  async run(ctx) {
+    const path = await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/claim`);
+    return (await ctx.api.request("DELETE", path, { query: ctx.input.force ? { force: true } : void 0 })).data;
+  }
+};
 var bulk = {
   path: ["issues", "bulk-status"],
   summary: "Change the status of every issue matching a filter. Dry run unless --apply.",
@@ -1030,7 +1206,9 @@ var bulk = {
     ids: { type: "list", value: "<id,...>", description: "Exactly these issues." },
     ...FILTERS,
     all: { type: "boolean", description: "Every issue of the project (required when no other selector is given)." },
-    apply: { type: "boolean", description: "Actually change them. Default is a dry run." }
+    apply: { type: "boolean", description: "Actually change them. Default is a dry run." },
+    ...FIXED_IN,
+    ...WHY
   },
   examples: [
     { command: "tracksiy issues bulk-status --to resolved --until 30d", description: "Preview resolving everything not seen for 30 days." },
@@ -1045,12 +1223,13 @@ var bulk = {
       ids: ctx.input.ids?.map(String),
       filter: hasFilter ? filter : void 0,
       all: ctx.input.all || void 0,
-      dryRun: !ctx.input.apply
+      dryRun: !ctx.input.apply,
+      ...whyBody(ctx.input)
     });
     return ctx.api.send("POST", await projectPath(ctx, "issues/status"), body);
   }
 };
-var issues_default = [list, view, resolve2, ignore, unresolve, bulk];
+var issues_default = [list, view, resolve2, ignore, unresolve, bulk, comment, activity, verifyFixed, claim, unclaim];
 
 // src/commands/projects.ts
 var create = {
@@ -1149,12 +1328,12 @@ var onboarding = {
 var projects_default = [create, verify, onboarding];
 
 // src/commands/alerts.ts
-var RECIPIENT_TYPES = ["email", "webhook", "discord", "googlechat", "telegram"];
+var RECIPIENT_TYPES = ["email", "webhook", "discord", "googlechat", "telegram", "peerpacket"];
 var DECLARE = {
   recipient: {
     type: "list",
     value: "email|<type>:<url>",
-    description: `Who is told. Repeatable. \`email\` alone reaches the members of the project's teams; webhook, discord, googlechat and telegram take a URL: \`<type>:<url>\` (telegram: the Bot API sendMessage URL with chat_id).`
+    description: `Who is told. Repeatable. \`email\` alone reaches the members of the project's teams; webhook, discord, googlechat and telegram take a URL: \`<type>:<url>\` (telegram: the Bot API sendMessage URL with chat_id; peerpacket: https://peerpacket.com/channels/<channel>?to=<handle>&as=<author>&key=<pp_live_\u2026> -- each alert becomes a ticket for that agent, closed when its issues are resolved).`
   },
   delivery: { type: "string", enum: ["immediate", "digest"], description: "For --recipient: send each alert now, or batch into the digest hours. Default immediate." },
   "new-issue": { type: "boolean", description: "Alert on every new issue (default true). --no-new-issue to turn off." },
@@ -1231,7 +1410,8 @@ var set = {
   flags: DECLARE,
   examples: [
     { command: "tracksiy alerts set --recipient email --threshold 50/10", description: "Email the project's team on new issues, on bursts, and on downtime." },
-    { command: "tracksiy alerts set --recipient 'telegram:https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>' --delivery digest", description: "Telegram, batched into the digest hours." }
+    { command: "tracksiy alerts set --recipient 'telegram:https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>' --delivery digest", description: "Telegram, batched into the digest hours." },
+    { command: "tracksiy alerts set --recipient 'peerpacket:https://peerpacket.com/channels/shop-ops?to=shop-agent&as=tracksiy-alerts&key=pp_live_\u2026'", description: "Alerts land as PeerPacket tickets for the shop's agent." }
   ],
   output: "The stored alerting state, same shape as `alerts get`.",
   text: rulesText,
@@ -1466,7 +1646,7 @@ var releases_default = [list3, health2, declare];
 
 // src/commands/artifacts.ts
 import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
 
 // src/lib/sourcemaps.ts
 import { createHash } from "node:crypto";
@@ -1841,7 +2021,7 @@ skipped, no source map: ${d.skipped.join(", ")}` : ""}`,
 };
 function uuidFromDebugMeta(path) {
   if (!existsSync3(path)) throw usageError("bad_path", `No such file: ${path}`);
-  const m = /ProguardUuids\s*[=:]\s*([0-9a-fA-F-]{36})/.exec(readFileSync3(path, "utf8"));
+  const m = /ProguardUuids\s*[=:]\s*([0-9a-fA-F-]{36})/.exec(readFileSync4(path, "utf8"));
   if (!m) throw usageError("bad_value", `No ProguardUuids entry in ${path}`);
   return m[1].toLowerCase();
 }
@@ -2053,16 +2233,16 @@ var support = {
 var support_default = [support];
 
 // src/commands/init.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "node:fs";
 import { appendFile, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join4, resolve as resolve4 } from "node:path";
 
 // src/lib/detect.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, readdirSync } from "node:fs";
 import { basename, join as join3 } from "node:path";
 function readJson(path) {
   try {
-    return JSON.parse(readFileSync4(path, "utf8"));
+    return JSON.parse(readFileSync5(path, "utf8"));
   } catch {
     return void 0;
   }
@@ -2134,7 +2314,7 @@ function detect(dir, guideBase) {
   }
   const py = has(dir, "pyproject.toml", "requirements.txt", "Pipfile", "manage.py");
   if (py) {
-    const text = ["pyproject.toml", "requirements.txt", "Pipfile"].map((f) => existsSync4(join3(dir, f)) ? readFileSync4(join3(dir, f), "utf8") : "").join("\n").toLowerCase();
+    const text = ["pyproject.toml", "requirements.txt", "Pipfile"].map((f) => existsSync4(join3(dir, f)) ? readFileSync5(join3(dir, f), "utf8") : "").join("\n").toLowerCase();
     const fw = existsSync4(join3(dir, "manage.py")) || text.includes("django") ? "django" : text.includes("fastapi") ? "fastapi" : text.includes("flask") ? "flask" : "python";
     evidence.push(`${py} (${fw})`);
     return { platform: fw === "python" ? "python" : `python-${fw}`, framework: fw, surfaces: ["backend"], env: { backend: "SENTRY_DSN" }, guide: guide("python-sentry-sdk"), name, evidence };
@@ -2230,7 +2410,7 @@ ${d.steps.map((s, i) => `${i + 1}. ${s.detail}${s.run ? `
       if (!existsSync5(envPath)) {
         throw usageError("no_env_file", `${envPath} does not exist; nothing was written to it.`, "Create it (and make sure it is gitignored), or set the variables yourself from `keys` in the output.");
       }
-      const current = readFileSync5(envPath, "utf8");
+      const current = readFileSync6(envPath, "utf8");
       const added = [];
       const kept = [];
       let block = "";
@@ -2285,12 +2465,13 @@ function camel(name) {
 }
 
 // src/core/args.ts
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync7 } from "node:fs";
 var GLOBAL_FLAGS = {
   org: { type: "string", value: "<slug>", description: "Organization slug. Env: TRACKSIY_ORG. Default: .tracksiy.json, saved login, or your only organization." },
   project: { type: "string", value: "<slug>", description: "Project slug, or org/project. Env: TRACKSIY_PROJECT. Default: .tracksiy.json." },
   url: { type: "string", value: "<url>", description: "Server root. Env: TRACKSIY_URL. Default: https://tracksiy.com." },
   token: { type: "string", value: "<token>", description: "API token. Env: TRACKSIY_TOKEN (preferred: flags show up in process lists)." },
+  as: { type: "string", value: "<handle>", description: "Your agent handle, recorded on issue activity and claims (X-Tracksiy-Agent). Env: TRACKSIY_AGENT. Default: the token's label." },
   json: { type: "boolean", description: "Print JSON. This is the default whenever stdout is not a terminal." },
   format: { type: "string", enum: ["json", "text"], description: "Output format. Env: TRACKSIY_FORMAT." },
   select: { type: "list", value: "<fields>", description: "Keep only these fields of `data`, comma-separated; dot paths reach into objects and lists (e.g. issues.id,issues.title)." },
@@ -2301,7 +2482,7 @@ var GLOBAL_FLAGS = {
 };
 var stdinCache;
 function readStdin() {
-  stdinCache ??= readFileSync6(0, "utf8");
+  stdinCache ??= readFileSync7(0, "utf8");
   return stdinCache;
 }
 function parseJsonValue(name, raw) {
@@ -2309,7 +2490,7 @@ function parseJsonValue(name, raw) {
   if (raw === "-") text = readStdin();
   else if (raw.startsWith("@")) {
     try {
-      text = readFileSync6(raw.slice(1), "utf8");
+      text = readFileSync7(raw.slice(1), "utf8");
     } catch (err) {
       throw usageError("bad_value", `--${name}: cannot read ${raw.slice(1)}: ${err.message}`);
     }
@@ -2649,7 +2830,7 @@ function makeContext(spec, input, globals, surface, io) {
     if (!quiet || surface === "mcp" && config.verbose) io.stderr(`${message}
 `);
   };
-  const api2 = new Api({ url: config.url, token: config.token, timeoutMs: config.timeoutMs, verbose: config.verbose, log, fetch: io.fetch });
+  const api2 = new Api({ url: config.url, token: config.token, agent: config.agent, timeoutMs: config.timeoutMs, verbose: config.verbose, log, fetch: io.fetch });
   let orgs2;
   const visible = () => {
     orgs2 ??= api2.get("organizations").catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracksiy",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Agent-first CLI and MCP server for Tracksiy: errors, uptime, alerts, releases and source maps, from one token.",
   "type": "module",
   "bin": {