pi-gauntlet 5.5.0 → 5.5.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.5.1 - 2026-09-10
+
+- `linear`: copyable, version-scoped recovery for attachment-download 401s resolves the decrypted credential through linearis instead of reading encrypted token storage. Restricts credential delivery to HTTPS Linear uploads, rejects redirects, and checks downloaded bytes; an offline regression executes the documented example.
+
 ## v5.5.0 - 2026-09-10
 
 - `writing-plans`: every task carries a `**Tests:**` block - scoped commands anchored to the task's `Test:` paths, optional `via:` entry point, or `none: <category>`; the plan grammar `plan_check` enforces moves to `skills/writing-plans/reference/plan-contract.md`. (#28)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/linear/SKILL.md

@@ -24,7 +24,9 @@ this skill alters re-gates.
 Preferred: `linearis` on PATH and authenticated (`linearis auth status`). Token
 resolution order: `--api-token`, `LINEAR_API_TOKEN`, `~/.linearis/token`. This is a
 preference, not a precondition - a missing or unauthenticated CLI degrades Linear
-functionality and is reported, never blocks the run.
+functionality and is reported, never blocks the run. The token file is encrypted
+storage: never use its contents as an HTTP credential or infer the credential type
+from its `v1:` storage-format prefix. Resolve it through linearis instead.
 
 > **No `linearis` installed?** If `command -v linearis` fails, fall back to a
 > **Linear MCP server** when the harness has one configured - its tools cover the
@@ -192,7 +194,7 @@ Safety rules, in addition to the write gate above:
 | Symptom | Cause | Fix |
 |---|---|---|
 | 401 | Not authenticated / expired token | `linearis auth status`; re-auth - unless the download row below applies. |
-| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Fetch the URL with the bare key, or use a version without the bug once one ships. |
+| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Use the recovery below, or use a version without the bug once one ships. |
 | Issue not found | Wrong workspace, or issue archived | Confirm workspace; check archived state. |
 | Status not found | Status name doesn't match the team's workflow states | List the team's states before setting one. |
 | Missing `--team` error on create | `--team` is required | Supply `--team <default team>`. |
@@ -203,6 +205,45 @@ Safety rules, in addition to the write gate above:
 | Read is slow | Big ticket with many comments/attachments | Drop `--with-*` flags not needed. |
 | Parser-shape failure on a documented invocation: unknown command/option, unexpected argument | Section 3's snapshot may have drifted from the installed CLI | Re-read that subcommand's `--help`; report the row stale **only if** help actually contradicts it, then follow help |
 
+For that download-only 401, this 2026.7.0/2026.8.0 workaround calls linearis's
+version-specific internal `getApiToken` API. Supply the fresh `uploads.linear.app` URL
+from `issues read --with-attachments` and an output path. It rejects other hosts and
+redirects, sends the resolved key without `Bearer`, writes only a non-empty response,
+and never prints or stores the key separately:
+
+<!-- linear-download-recovery:start -->
+```bash
+download_linear_asset() {
+  LINEARIS_BIN="${LINEARIS_BIN:-$(command -v linearis)}" node --input-type=module - "$1" "$2" <<'NODE'
+import { realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [urlText, output] = process.argv.slice(2);
+const url = new URL(urlText);
+if (url.protocol !== "https:" || url.hostname !== "uploads.linear.app")
+  throw new Error("refusing to send a credential outside https://uploads.linear.app");
+const packageRoot = dirname(dirname(realpathSync(process.env.LINEARIS_BIN)));
+const { getApiToken } = await import(pathToFileURL(join(packageRoot, "dist/common/auth.js")));
+const response = await fetch(url, {
+  headers: { Authorization: getApiToken({}) },
+  redirect: "error",
+});
+if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+const bytes = new Uint8Array(await response.arrayBuffer());
+if (bytes.byteLength === 0) throw new Error("download failed: empty response");
+writeFileSync(output, bytes);
+console.log(`downloaded ${bytes.byteLength} bytes to ${output}`);
+NODE
+}
+download_linear_asset 'https://uploads.linear.app/...' '/tmp/attachment'
+```
+<!-- linear-download-recovery:end -->
+
+Do not declare the attachment inaccessible until this recovery used the resolved
+credential; reading `~/.linearis/token` directly does not count. Afterward, confirm the
+reported byte count and inspect the file type before consuming or extracting it.
+
 The last row's trigger is deliberately narrow. Data, auth, status-name, and root-thread
 validation errors have their own rows above and are **not** drift - routing them to "the
 skill is stale" would misdiagnose ordinary failures. This row is the reactive path for