pi-quiver 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -8,6 +8,19 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v6.1.0 - 2026-09-15
+
+- `slack`: tokens also resolve from a fixed per-user file - `$XDG_CONFIG_HOME/pi-quiver/.env` or `~/.config/pi-quiver/.env` (Linux/macOS), `%APPDATA%\pi-quiver\.env` (Windows) - after process env, the repo `.env`, and the primary checkout's `.env`. Every rung now falls through when it lacks the key; a repo `.env` holding only the bot token no longer blocks the user token. Breaking: an unreadable `.env` at any rung propagates the raw filesystem error instead of collapsing to `missing_token`; the `missing_token` message now lists every checked path (#22).
+- `slack`: every `channel` parameter accepts `@name` or a user ID (`U...`/`W...`) and targets that person's DM - `resolveChannel` opens it via `conversations.open` (needs `im:write`; `slack_thread` DM reads need `im:history`) and tools echo the resulting `D...`. Cached display/real-name aliases are trusted only after a `slack_cache_refresh` snapshot (#20).
+
+## v6.0.1 - 2026-09-13
+
+- `session-name` Herdr sink tolerates herdr-ntfy-notify's armed marker: exactly one leading `* ` on the live label no longer counts as a human rename, is preserved on every rename and on the shutdown restore, and its removal keeps the claim (#19).
+- `release.sh <level>` promotes the CHANGELOG `## Unreleased` section to `## vX.Y.Z - <date>` and commits it with `package.json` in the single `Release X.Y.Z` commit; a missing or empty section fails the run. New CONFIG field `CHANGELOG_HEADING`.
+- Release skill and `/release` prompt: a user instruction naming the level is the approval - no proposal step or re-confirmation; bundled follow-ups run after `verify`.
+- AGENTS.md rewritten to always-on essentials plus routing; shared core bumped to v3.
+- Added `.pi/gauntlet-overrides.md` (`tracker: github`, release path, write-gate carve-out for user-named writes).
+
 ## v6.0.0 - 2026-09-10
 
 - doc_to_md (Excel, breaking): `maxCellsPerSheet` is removed from the tool schema, CLI (`--max-cells-per-sheet`), and `quiver.docToMd` settings; a leftover key is reported by the settings lint. Sheet indices are now 0-based workbook positions covering worksheets and chartsheets, so embedded-image files move from `<stem>-s1-<n>.*` to `<stem>-s0-<n>.*` and `SheetInfo.index` is rebased.

package/README.md

@@ -70,7 +70,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
 | `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
 | `extensions/provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
-| `extensions/slack.ts` | `slack_search`, `slack_thread`, `slack_post`, `slack_update`, `slack_delete`, `slack_pin`, `slack_upload`, `slack_cache_refresh` | Context-safe Slack search/threads/posting with dual `user`/`bot` token identities, a workspace-keyed channel/user name->ID cache, fetch-style output size gating, and a transactional headline+detail-thread announce protocol with a documented recovery path. OFF by default. Behavior lives in `lib/slack-core.ts` and `lib/slack-cache.ts`. |
+| `extensions/slack.ts` | `slack_search`, `slack_thread`, `slack_post`, `slack_update`, `slack_delete`, `slack_pin`, `slack_upload`, `slack_cache_refresh` | Context-safe Slack search/threads/posting with dual `user`/`bot` token identities, a workspace-keyed channel/user name->ID cache, DM targets by `@name` / user ID, fetch-style output size gating, and a transactional headline+detail-thread announce protocol with a documented recovery path. OFF by default. Behavior lives in `lib/slack-core.ts` and `lib/slack-cache.ts`. |
 
 Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md), [doc/doc-to-md.md](doc/doc-to-md.md), [doc/slack.md](doc/slack.md).
 
@@ -200,7 +200,7 @@ survive untouched.
 
 `sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `rules` appends house conventions to the naming prompt (later rules win when they conflict with the built-ins). Literal, case-insensitive `deny` phrases are stripped from every name; whitespace inside a phrase is loose, so `"acme corp"` also catches `AcmeCorp`. `revisitFirstTurn` re-evaluates the name once that many model round trips have completed, while `revisitEveryTurns` does so at every multiple; both default to `0` (off) because each revisit costs another short LLM call. For example, `10` and `100` mark round trips 10, 100, 200, 300. Revisits only run when the agent has fully settled (idle, nothing queued) - an automated multi-turn run such as a subagent chain is never renamed or delayed mid-flight; cadence points it crossed fire once, at the settle. A machine-generated name is replaced when stale. A name set by a human is never overwritten: the extension strongly prefers it, and announces a suggestion only when the work has clearly moved on. Counts come from the persisted transcript, so they survive resume.
 
-`herdrTab` (default `true`) mirrors the same curated label to the Herdr tab bar over Herdr's unix socket, independent of `ghosttyTab` - either sink can be toggled off without affecting the other. It's claim-once: the extension adopts a tab only while it still shows its default numeric label (its live 1-based position among the workspace's tabs); a manually renamed tab, or one renamed mid-session by hand, is never touched again for that session - the human's label always wins. On every shutdown (quit, reload, `/new`, resume, fork) a claimed tab's label is restored to its then-current default position, so a successor session in the same pane can claim cleanly. It only ever runs in TUI mode, on an attached TTY, under Herdr (`HERDR_ENV`/`HERDR_TAB_ID`/`HERDR_SOCKET_PATH` all set) - `pi -p`/json/rpc runs and background subagents never touch the tab. Caveats: a hard crash (`kill -9`) skips the restore and leaves the stale label - rename the tab by hand to recover; and the restored label is internally a custom name (Herdr has no clear-to-auto API), so that tab keeps a number-looking label but stops renumbering on later tab closes/reorders.
+`herdrTab` (default `true`) mirrors the same curated label to the Herdr tab bar over Herdr's unix socket, independent of `ghosttyTab` - either sink can be toggled off without affecting the other. It's claim-once: the extension adopts a tab only while it still shows its default numeric label (its live 1-based position among the workspace's tabs); a manually renamed tab, or one renamed mid-session by hand, is never touched again for that session - the human's label always wins. One exception: exactly one leading `* ` (herdr-ntfy-notify's armed marker) is not a human rename - it is preserved across renames and the shutdown restore, and removing it keeps the claim. On every shutdown (quit, reload, `/new`, resume, fork) a claimed tab's label is restored to its then-current default position, so a successor session in the same pane can claim cleanly. It only ever runs in TUI mode, on an attached TTY, under Herdr (`HERDR_ENV`/`HERDR_TAB_ID`/`HERDR_SOCKET_PATH` all set) - `pi -p`/json/rpc runs and background subagents never touch the tab. Caveats: a hard crash (`kill -9`) skips the restore and leaves the stale label - rename the tab by hand to recover; and the restored label is internally a custom name (Herdr has no clear-to-auto API), so that tab keeps a number-looking label but stops renumbering on later tab closes/reorders.
 
 `fastMode` only affects `claude-opus-4-8` and `claude-opus-5` requests on Anthropic's `anthropic-messages` API; enabling it opts into premium fast-mode pricing. `--fast` forces it on for one launch; `/fast on|off` toggles live. Proxy providers (opencode, cloudflare-ai-gateway) are excluded. `fastMode`'s header injection needs the `before_provider_headers` hook (pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5); on older pi the beta header is silently not sent. The `anthropic-beta` header is discovered at request time by probing pi's own request assembly (no network), so conditional betas pi adds - e.g. `server-side-fallback-2026-07-01` for models with server-side fallback - are preserved alongside `fast-mode-2026-02-01`. If the probe fails, the header falls back to the static OAuth-identity + fast-mode list. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
 
@@ -280,7 +280,7 @@ Operational notes:
 | `botTokenEnv` | `SLACK_BOT_TOKEN` | Env var name holding the bot token. |
 | `uploadThresholdChars` | `4000` | Link-collapsed length above which an announce/thread detail body is delivered as a file upload instead of inline text. |
 
-Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env and then `.env` (or the primary checkout's, for a worktree with none). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
+Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env, then the repo `.env`, then the primary checkout's `.env` (linked worktrees), then a per-user `~/.config/pi-quiver/.env` (`$XDG_CONFIG_HOME` / `%APPDATA%` aware); a file lacking the key falls through to the next rung - see [doc/slack.md](doc/slack.md). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
 
 ### doc_to_md settings
 
@@ -392,7 +392,9 @@ bash .agents/skills/release/scripts/release.sh patch        # or minor / major
 bash .agents/skills/release/scripts/release.sh --dry-run patch
 ```
 
-It bumps `package.json`, commits `Release <version>`, runs the tests, creates
-and pushes the `vX.Y.Z` tag, then monitors the publish. See
-`.agents/skills/release/SKILL.md` for the full flow (`sync-presets` migrates
-old git-tag pins to `npm:pi-quiver@<version>`).
+It promotes the `## Unreleased` CHANGELOG section to `## vX.Y.Z - <date>`,
+bumps `package.json`, commits `Release <version>`, runs the tests, creates and
+pushes the `vX.Y.Z` tag, then monitors the publish. See
+`.agents/skills/release/SKILL.md` for the full flow (`sync-presets --apply`
+rewrites same-form `npm:pi-quiver@<old>` pins; git-tag pins are reported for
+manual migration).

package/extensions/session-name.ts

@@ -498,8 +498,10 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 
 	// Herdr sink. Claim-once: adopt the tab only while it shows its default
 	// (position) label; a human rename - before or during the session - wins
-	// permanently. All syncs serialize on one chain so overlapping hooks never
-	// interleave a read with a rename.
+	// permanently. The one exception is exactly one leading "* ": that is
+	// herdr-ntfy-notify's armed marker, ignored for ownership and carried
+	// through on every write. All syncs serialize on one chain so overlapping
+	// hooks never interleave a read with a rename.
 	// Used both for turn_start syncs (bounds a wedged-but-accepting Herdr so it
 	// can't stall the turn) and for the session_end restore.
 	const HERDR_TIMEOUT_MS = 500;
@@ -511,6 +513,13 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		return siblings.findIndex((t) => t.tab_id === tabId) + 1;
 	};
 
+	const ARMED_PREFIX = "* ";
+	const matchOwned = (live: string, expected: string): { owned: boolean; armed: boolean } => {
+		if (live === expected) return { owned: true, armed: false };
+		if (live === ARMED_PREFIX + expected) return { owned: true, armed: true };
+		return { owned: false, armed: false };
+	};
+
 	const syncHerdrTab = (cfg: Config, label: string | null, mode: Mode | undefined): Promise<void> => {
 		const run = async (): Promise<void> => {
 			if (!cfg.herdrTab || mode !== "tui" || !label) return;
@@ -524,23 +533,25 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 				const position = positionOf(tabs, tabId);
 				if (position === -1) return; // stale tab id (pane moved); retry harmlessly
 				const own = tabs.find((t) => t.tab_id === tabId)!;
-				if (own.label !== String(position)) {
+				const owned = matchOwned(own.label, String(position));
+				if (!owned.owned) {
 					herdrClaim = "backed-off"; // human (or crashed predecessor) owns it
 					return;
 				}
-				if (await renameTab(sock, tabId, label, HERDR_TIMEOUT_MS)) {
+				if (await renameTab(sock, tabId, (owned.armed ? ARMED_PREFIX : "") + label, HERDR_TIMEOUT_MS)) {
 					herdrClaim = { lastWritten: label };
 				}
 				return;
 			}
 			const live = await getTab(sock, tabId, HERDR_TIMEOUT_MS);
 			if (!live) return; // failed read is not a human rename; stay claimed
-			if (live.label !== herdrClaim.lastWritten) {
+			const owned = matchOwned(live.label, herdrClaim.lastWritten);
+			if (!owned.owned) {
 				herdrClaim = "backed-off";
 				return;
 			}
 			if (label === herdrClaim.lastWritten) return;
-			if (await renameTab(sock, tabId, label, HERDR_TIMEOUT_MS)) herdrClaim.lastWritten = label;
+			if (await renameTab(sock, tabId, (owned.armed ? ARMED_PREFIX : "") + label, HERDR_TIMEOUT_MS)) herdrClaim.lastWritten = label;
 		};
 		herdrChain = herdrChain.then(run, run);
 		return herdrChain;
@@ -555,12 +566,14 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 			const sock = process.env.HERDR_SOCKET_PATH as string;
 			const tabId = process.env.HERDR_TAB_ID as string;
 			const live = await getTab(sock, tabId, HERDR_TIMEOUT_MS);
-			if (!live || live.label !== herdrClaim.lastWritten) return; // human's label wins
+			if (!live) return;
+			const owned = matchOwned(live.label, herdrClaim.lastWritten);
+			if (!owned.owned) return; // human's label wins
 			const tabs = await listTabs(sock, HERDR_TIMEOUT_MS);
 			if (!tabs) return;
 			const position = positionOf(tabs, tabId);
 			if (position === -1) return;
-			await renameTab(sock, tabId, String(position), HERDR_TIMEOUT_MS);
+			await renameTab(sock, tabId, (owned.armed ? ARMED_PREFIX : "") + String(position), HERDR_TIMEOUT_MS);
 		};
 		herdrChain = herdrChain.then(run, run);
 		return herdrChain;

package/extensions/slack.ts

@@ -269,9 +269,9 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Thread",
 			promptSnippet: "Read all replies in a Slack thread",
 			description:
-				'Read a Slack thread via conversations.replies. Always uses the "user" identity (no `as` param). Provide either `channel` (#name or channel ID; user @names not accepted) plus `ts`, or a `permalink` (parsed for channel+ts). Paginates by cursor until Slack reports no more replies or a cap of 50 pages / 5,000 messages is hit; the result carries a `complete` flag and a resumable `next_cursor` when capped. Caveat: since 2025-05-29, conversations.replies is rate-limited to ~1 request/minute (limit capped at 15) for apps that are neither Marketplace-listed nor classified internal - hitting that throttle mid-pagination returns the messages collected so far plus a caveat and a resumable cursor instead of spinning. Output is size-gated like slack_search.',
+				'Read a Slack thread via conversations.replies. Always uses the "user" identity (no `as` param). Provide either `channel` (#name, channel ID, @name, or user ID (DM)) plus `ts`, or a `permalink` (parsed for channel+ts). Paginates by cursor until Slack reports no more replies or a cap of 50 pages / 5,000 messages is hit; the result carries a `complete` flag and a resumable `next_cursor` when capped. Caveat: since 2025-05-29, conversations.replies is rate-limited to ~1 request/minute (limit capped at 15) for apps that are neither Marketplace-listed nor classified internal - hitting that throttle mid-pagination returns the messages collected so far plus a caveat and a resumable cursor instead of spinning. Output is size-gated like slack_search.',
 			parameters: Type.Object({
-				channel: Type.Optional(Type.String({ description: "#name or channel ID (user @names not accepted)" })),
+				channel: Type.Optional(Type.String({ description: "#name, channel ID, @name, or user ID (DM)" })),
 				ts: Type.Optional(Type.String({ description: "Thread parent timestamp" })),
 				permalink: Type.Optional(Type.String({ description: "A Slack message permalink URL to parse channel+ts from" })),
 				cursor: Type.Optional(Type.String({ description: "Resume pagination from a next_cursor returned by a prior capped call" })),
@@ -279,7 +279,8 @@ export default function slackExtension(pi: ExtensionAPI) {
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {
 					const { deps, cacheCtx } = await resolveCall("user", cfg, ctx, signal, repoRoot);
-					const channel = params.channel !== undefined ? await resolveChannel(params.channel, cacheCtx) : undefined;
+					const channel =
+						params.permalink === undefined && params.channel !== undefined ? await resolveChannel(params.channel, cacheCtx) : undefined;
 					const result = await readThread({ channel, ts: params.ts, permalink: params.permalink, cursor: params.cursor }, deps);
 					return {
 						content: [{ type: "text" as const, text: threadResultText(result) }],
@@ -296,10 +297,10 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Post",
 			promptSnippet: "Post a Slack message, reply, or headline+detail announcement",
 			description:
-				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name or a channel ID (user @names not accepted). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact.",
+				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact.",
 			parameters: Type.Object({
 				as: IDENTITY,
-				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
+				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				text: Type.Optional(Type.String({ description: "Message text, or the announce headline when thread_body is set" })),
 				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
 				thread_ts: Type.Optional(Type.String({ description: "Reply into this existing thread instead of posting a new headline" })),
@@ -378,10 +379,10 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Update",
 			promptSnippet: "Edit an existing Slack message",
 			description:
-				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name or a channel ID (user @names not accepted). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).',
+				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).',
 			parameters: Type.Object({
 				as: IDENTITY,
-				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
+				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				ts: Type.String({ description: "Timestamp of the message to edit" }),
 				text: Type.Optional(Type.String()),
 				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
@@ -408,10 +409,10 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Delete",
 			promptSnippet: "Delete a Slack message",
 			description:
-				'Delete a message via chat.delete, as `as: "user"` or `as: "bot"`. `channel` accepts #name or a channel ID (user @names not accepted). Only the identity that originally posted the message can delete it (Slack constraint; surfaced as an error otherwise).',
+				'Delete a message via chat.delete, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can delete it (Slack constraint; surfaced as an error otherwise).',
 			parameters: Type.Object({
 				as: IDENTITY,
-				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
+				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				ts: Type.String({ description: "Timestamp of the message to delete" }),
 			}),
 			async execute(_toolCallId, params, signal) {
@@ -434,10 +435,10 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Pin",
 			promptSnippet: "Pin a Slack message to its channel",
 			description:
-				'Pin a message via pins.add, as `as: "user"` or `as: "bot"`. `channel` accepts #name or a channel ID (user @names not accepted). Slack errors are mapped: already_pinned, not_pinnable (this message type cannot be pinned), too_many_pins (the channel hit Slack\'s pin limit).',
+				'Pin a message via pins.add, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Slack errors are mapped: already_pinned, not_pinnable (this message type cannot be pinned), too_many_pins (the channel hit Slack\'s pin limit).',
 			parameters: Type.Object({
 				as: IDENTITY,
-				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
+				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				ts: Type.String({ description: "Timestamp of the message to pin" }),
 			}),
 			async execute(_toolCallId, params, signal) {
@@ -460,10 +461,10 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Upload",
 			promptSnippet: "Upload a file to a Slack channel or thread",
 			description:
-				'Upload a file to Slack (getUploadURLExternal -> upload -> completeUploadExternal), as `as: "user"` or `as: "bot"`. `channel` accepts #name or a channel ID (user @names not accepted). `path` is an absolute path or resolved relative to the current working directory; a missing file errors before any network call. `filename` defaults to the path\'s basename. Optional `title`, `thread_ts` (attach to an existing thread), and `initial_comment`.',
+				'Upload a file to Slack (getUploadURLExternal -> upload -> completeUploadExternal), as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). `path` is an absolute path or resolved relative to the current working directory; a missing file errors before any network call. `filename` defaults to the path\'s basename. Optional `title`, `thread_ts` (attach to an existing thread), and `initial_comment`.',
 			parameters: Type.Object({
 				as: IDENTITY,
-				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
+				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				path: Type.String({ description: "Absolute path, or a path relative to the current working directory" }),
 				filename: Type.Optional(Type.String({ description: "Defaults to the basename of path" })),
 				title: Type.Optional(Type.String()),

package/lib/slack-cache.ts

@@ -119,13 +119,21 @@ function toUserEntry(u: SlackUser): UserEntry {
 	};
 }
 
+/** DM conversations are opened per identity: Slack returns the existing D... for a repeat call, so this is idempotent and safe to retry. */
+async function openDm(userId: string, ctx: CacheCtx): Promise<string> {
+	const data = await ctx.apiCall("conversations.open", ctx.token, { users: userId }, { retry: true, signal: ctx.signal });
+	const channel = data.channel as { id?: unknown } | undefined;
+	if (typeof channel?.id !== "string") {
+		throw new SlackError("unexpected_response", 'conversations.open returned an unexpected response: missing "channel.id".');
+	}
+	return channel.id;
+}
+
 export async function resolveChannel(input: string, ctx: CacheCtx): Promise<string> {
 	if (RAW_CHANNEL_ID.test(input)) return input;
-	if (input.startsWith("@")) {
-		throw new SlackError(
-			"invalid_channel",
-			`"${input}" looks like a user name, which is not accepted in a channel position (opening a DM is out of scope).`,
-		);
+	if (RAW_USER_ID.test(input) || input.startsWith("@")) {
+		const userId = await resolveUser(input, ctx);
+		return openDm(userId, ctx);
 	}
 	const name = stripPrefix(input);
 
@@ -189,22 +197,26 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 		const byUsername = cached.users[name];
 		if (byUsername) return byUsername.id;
 
-		const displayMatches = Object.values(cached.users).filter((u) => u.display_name === name);
-		if (displayMatches.length === 1) return displayMatches[0].id;
-		if (displayMatches.length > 1) {
-			throw new SlackError(
-				"ambiguous_user",
-				`Multiple users have display name "${name}": ${displayMatches.map((u) => u.id).join(", ")}.`,
-			);
-		}
+		// Same gate as resolveMentions' aliasTrusted: an alias match is conclusive only against a
+		// complete workspace snapshot; a partial cache may hold a different person with that alias.
+		if (cached.snapshot_at !== undefined) {
+			const displayMatches = Object.values(cached.users).filter((u) => u.display_name === name);
+			if (displayMatches.length === 1) return displayMatches[0].id;
+			if (displayMatches.length > 1) {
+				throw new SlackError(
+					"ambiguous_user",
+					`Multiple users have display name "${name}": ${displayMatches.map((u) => u.id).join(", ")}.`,
+				);
+			}
 
-		const realMatches = Object.values(cached.users).filter((u) => u.real_name === name);
-		if (realMatches.length === 1) return realMatches[0].id;
-		if (realMatches.length > 1) {
-			throw new SlackError(
-				"ambiguous_user",
-				`Multiple users have real name "${name}": ${realMatches.map((u) => u.id).join(", ")}.`,
-			);
+			const realMatches = Object.values(cached.users).filter((u) => u.real_name === name);
+			if (realMatches.length === 1) return realMatches[0].id;
+			if (realMatches.length > 1) {
+				throw new SlackError(
+					"ambiguous_user",
+					`Multiple users have real name "${name}": ${realMatches.map((u) => u.id).join(", ")}.`,
+				);
+			}
 		}
 	}
 

package/lib/slack-core.ts

@@ -191,14 +191,25 @@ export function parseEnvFile(content: string): Map<string, string> {
 	return result;
 }
 
-function readEnvFile(dir: string): Map<string, string> | undefined {
+export function userConfigEnvPath(
+	env: Record<string, string | undefined>,
+	platform: NodeJS.Platform = process.platform,
+): string | undefined {
+	if (platform === "win32") {
+		return env.APPDATA ? join(env.APPDATA, "pi-quiver", ".env") : undefined;
+	}
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi-quiver", ".env");
+	if (env.HOME) return join(env.HOME, ".config", "pi-quiver", ".env");
+	return undefined;
+}
+
+function readEnvFile(path: string): Map<string, string> | undefined {
 	try {
-		return parseEnvFile(readFileSync(join(dir, ".env"), "utf8"));
+		return parseEnvFile(readFileSync(path, "utf8"));
 	} catch (err) {
-		// Deliberate: a genuinely absent .env degrades to "token not found", not a thrown error.
+		// Deliberate: a genuinely absent .env degrades to "token not found". Anything else (permissions,
+		// a directory at that path) is a misconfiguration the caller must see, so it propagates raw.
 		if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
-		// Present but unreadable (e.g. permissions): re-thrown so callers treat it as present-but-empty,
-		// not absent - this must NOT authorize the primary-checkout fallback.
 		throw err;
 	}
 }
@@ -208,45 +219,29 @@ export function resolveToken(
 	cfg: SlackConfig,
 	env: Record<string, string | undefined>,
 	repoRoot: string,
+	platform: NodeJS.Platform = process.platform,
 ): string {
 	const envVar = identity === "user" ? cfg.userTokenEnv : cfg.botTokenEnv;
 
 	const fromEnv = env[envVar];
 	if (fromEnv) return fromEnv;
 
-	let repoEnvFile: Map<string, string> | undefined;
-	let repoEnvUnreadable = false;
-	try {
-		repoEnvFile = readEnvFile(repoRoot);
-	} catch {
-		repoEnvUnreadable = true;
-	}
+	const candidates = [join(repoRoot, ".env")];
+	const primaryRoot = primaryCheckoutRoot(repoRoot);
+	if (primaryRoot !== undefined && primaryRoot !== repoRoot) candidates.push(join(primaryRoot, ".env"));
+	const userPath = userConfigEnvPath(env, platform);
+	if (userPath !== undefined) candidates.push(userPath);
 
-	if (repoEnvFile) {
-		// An empty (after quote-strip) .env value is treated as missing, not a usable empty token.
-		const value = repoEnvFile.get(envVar);
+	for (const path of candidates) {
+		const parsed = readEnvFile(path);
+		// An empty (after quote-strip) value is treated as missing, not a usable empty token.
+		const value = parsed?.get(envVar);
 		if (value) return value;
-	} else if (!repoEnvUnreadable) {
-		// File-level fallback only, per spec: this only triggers when the worktree root has no .env at
-		// all (ENOENT); an existing-but-unreadable local .env blocks the fallback just like an existing
-		// one that lacks this key.
-		const primaryRoot = primaryCheckoutRoot(repoRoot);
-		if (primaryRoot && primaryRoot !== repoRoot) {
-			// Best-effort: any error reading the primary .env (missing or otherwise) just means no fallback.
-			let primaryEnvFile: Map<string, string> | undefined;
-			try {
-				primaryEnvFile = readEnvFile(primaryRoot);
-			} catch {
-				primaryEnvFile = undefined;
-			}
-			const value = primaryEnvFile?.get(envVar);
-			if (value) return value;
-		}
 	}
 
 	throw new SlackError(
 		"missing_token",
-		`No Slack ${identity} token: env var ${envVar} is empty and no .env entry was found.`,
+		`No Slack ${identity} token: env var ${envVar} is empty and no entry found in ${candidates.join(", ")}.`,
 	);
 }
 
@@ -279,11 +274,12 @@ export async function resolveCredential(
 	cfg: SlackConfig,
 	env: Record<string, string | undefined>,
 	repoRoot: string,
+	platform: NodeJS.Platform = process.platform,
 ): Promise<string> {
 	if (identity === "user" && cfg.userTokenCommand) {
 		return runCredentialCommand(cfg.userTokenCommand, Math.ceil(cfg.userTokenCommandTimeoutSeconds * 1000));
 	}
-	return resolveToken(identity, cfg, env, repoRoot);
+	return resolveToken(identity, cfg, env, repoRoot, platform);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",