@gethmy/mcp 3.4.1 → 3.6.0

package/README.md

@@ -434,7 +434,7 @@ curl -X GET "https://gethmy.com/api/v1/workspaces" \
 
 ### Global Configuration
 
-Stored in `~/.harmony-mcp/config.json`. Browser sign-in writes OAuth tokens (and nulls `apiKey`); API-key setup writes `apiKey` instead. The server prefers a live OAuth token and refreshes it automatically:
+Stored in `~/.hmy/agent/config.json`. Browser sign-in writes OAuth tokens (and nulls `apiKey`); API-key setup writes `apiKey` instead. The server prefers a live OAuth token and refreshes it automatically:
 
 ```json
 {
@@ -452,7 +452,7 @@ Stored in `~/.harmony-mcp/config.json`. Browser sign-in writes OAuth tokens (and
 
 ### Local Project Configuration
 
-Stored in `.harmony-mcp.json` in your project root:
+Stored in `.hmy.json` in your project root:
 
 ```json
 {
@@ -498,10 +498,10 @@ Skills:
     ~/.agents/skills/hmy/SKILL.md
 
 Context:
-  Local config: .harmony-mcp.json
+  Local config: .hmy.json
     Workspace: my-team-id
     Project: my-project-id
-  Global config: ~/.harmony-mcp/config.json
+  Global config: ~/.hmy/agent/config.json
     Workspace: (not set)
     Project: (not set)
 
@@ -515,7 +515,7 @@ Context:
 Add this to prevent accidentally committing local config:
 
 ```
-.harmony-mcp.json
+.hmy.json
 ```
 
 ## Architecture

package/dist/cli.js

@@ -21,12 +21,36 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
+function noteLegacyConfigDir(path) {
+  if (warnedLegacyConfigDir)
+    return;
+  warnedLegacyConfigDir = true;
+  console.error(`Harmony: reading the pre-#1082 config at ${path}. ` + `The current location is ${getConfigPath()}; ` + `run the agent daemon once to migrate, or move the file yourself.`);
+}
+function noteLegacyLocalPin(path) {
+  if (warnedLegacyLocalPin)
+    return;
+  warnedLegacyLocalPin = true;
+  console.error(`Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` + `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`);
+}
+function noteLocalPinRename(from, to) {
+  console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
+}
+function getHmyRootDir() {
+  return join(homedir(), CONFIG_DIR_NAME);
+}
 function getConfigDir() {
-  return join(homedir(), ".harmony-mcp");
+  return join(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+function getLegacyConfigDir() {
+  return join(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
+function getLegacyConfigPath() {
+  return join(getLegacyConfigDir(), "config.json");
+}
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
@@ -36,9 +60,14 @@ function findLocalConfigPath(cwd) {
   const { root } = parse(dir);
   for (;; ) {
     if (dir !== home && dir !== root) {
-      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync(candidate))
-        return candidate;
+      const current = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(current))
+        return current;
+      const legacy = join(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir)
@@ -61,9 +90,12 @@ function emptyConfig() {
   };
 }
 function loadConfig() {
-  const configPath = getConfigPath();
+  let configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync(configPath))
+      return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
   try {
     const data = readFileSync(configPath, "utf-8");
@@ -113,7 +145,11 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath ? join(dirname(foundPath), LOCAL_CONFIG_FILENAME) : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -125,6 +161,7 @@ function saveLocalConfig(config, cwd) {
   if (newConfig.projectId)
     cleanConfig.projectId = newConfig.projectId;
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
@@ -259,7 +296,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
 var init_config = () => {};
 
 // src/prompt-builder.ts
@@ -5693,7 +5730,7 @@ var TOOLS = {
     }
   },
   harmony_update_agent_progress: {
-    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
+    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live. `sessionStale: true` means it opened one IN PLACE OF a session the inactivity sweep had closed (card #1067): nobody stopped you and the new row keeps the old one's steering channel and driver, so carry on — but the id changed, so poll harmony_get_pending_messages with the new `session.id` from this reply, not the one you were holding. `liveSessionIdChanged: true` is the weaker cousin: the live session is simply not the one you started, so use the new id, but do NOT assume steering survived — read `instruction`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7654,6 +7691,32 @@ ${options}
       if (result.session === null) {
         untrack(cardId, deps.getScopeId?.());
       }
+      const scopeId = deps.getScopeId?.();
+      const ownSession = memSession && memSession.scopeId === scopeId ? memSession : undefined;
+      const knownSessionId = ownSession?.agentSessionId;
+      const liveSessionId = result.session?.id;
+      const idChangedUnderUs = knownSessionId !== undefined && liveSessionId !== undefined && liveSessionId !== knownSessionId;
+      if (idChangedUnderUs && ownSession && liveSessionId) {
+        ownSession.agentSessionId = liveSessionId;
+      }
+      const newSessionId = liveSessionId ? ` (${liveSessionId})` : "";
+      if (result.sessionStale) {
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          instruction: "Your previous session had gone stale, so this report opened a new one in its place — nobody stopped you, and it kept the steering channel and driver of the run it replaced. Do NOT abandon the work. Poll harmony_get_pending_messages with the NEW session id" + newSessionId + ", not the one you were holding."
+        };
+      }
+      if (idChangedUnderUs) {
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          liveSessionIdChanged: true,
+          instruction: "The live session on this card is no longer the one you started — it may have been reopened, or deliberately ended and replaced. Nobody stopped you, so carry on, but poll harmony_get_pending_messages with the session id from this reply" + newSessionId + ". If steering matters to this run, do not assume it survived: start a session deliberately with harmony_start_agent_session and steerable: true."
+        };
+      }
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
@@ -9410,6 +9473,7 @@ function ensureDir(dirPath) {
     mkdirSync5(dirPath, { recursive: true, mode: 493 });
   }
 }
+var CONFIG_DIR_MARKERS = [".hmy", ".harmony-mcp"];
 function writeFile(filePath, content, options = {}) {
   const exists = existsSync8(filePath);
   if (exists && !options.force) {
@@ -9417,7 +9481,7 @@ function writeFile(filePath, content, options = {}) {
   }
   try {
     ensureDir(dirname3(filePath));
-    const defaultMode = filePath.includes(".harmony-mcp") ? 384 : 420;
+    const defaultMode = CONFIG_DIR_MARKERS.some((marker) => filePath.includes(marker)) ? 384 : 420;
     const mode = options.mode ?? defaultMode;
     writeFileSync5(filePath, content, { mode });
     if (options.mode !== undefined) {
@@ -10586,14 +10650,15 @@ Specify the workspace with --workspace <id>, or select one below.`);
       console.log(`  ${colors.dim("Skipped tool allowlist — you'll be prompted per tool, or run /permissions in Claude Code later.")}`);
     }
   }
+  let writtenLocalConfigPath = null;
   if (selectedWorkspaceId || selectedProjectId) {
     const localConfig = {};
     if (selectedWorkspaceId)
       localConfig.workspaceId = selectedWorkspaceId;
     if (selectedProjectId)
       localConfig.projectId = selectedProjectId;
-    saveLocalConfig(localConfig, cwd);
-    console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(getLocalConfigPath(cwd), home))} ${colors.dim("(created)")}`);
+    writtenLocalConfigPath = saveLocalConfig(localConfig, cwd);
+    console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(writtenLocalConfigPath, home))} ${colors.dim("(created)")}`);
     if (selectedWorkspaceId || selectedProjectId) {
       setActiveContext({
         workspaceId: selectedWorkspaceId ?? null,
@@ -10623,7 +10688,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       console.log(`    Skills:    ${installMode === "global" ? "~/.agents/skills/ (global)" : ".claude/skills/ (local)"}`);
     }
     if (selectedWorkspaceId || selectedProjectId) {
-      console.log(`    Context:   ${formatPath(getLocalConfigPath(cwd), home)}`);
+      console.log(`    Context:   ${formatPath(writtenLocalConfigPath ?? getLocalConfigPath(cwd), home)}`);
     }
     console.log("");
     console.log(`  ${colors.bold("Usage:")}`);

package/dist/index.js

@@ -21,12 +21,36 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join as join2, parse, resolve } from "node:path";
+function noteLegacyConfigDir(path) {
+  if (warnedLegacyConfigDir)
+    return;
+  warnedLegacyConfigDir = true;
+  console.error(`Harmony: reading the pre-#1082 config at ${path}. ` + `The current location is ${getConfigPath()}; ` + `run the agent daemon once to migrate, or move the file yourself.`);
+}
+function noteLegacyLocalPin(path) {
+  if (warnedLegacyLocalPin)
+    return;
+  warnedLegacyLocalPin = true;
+  console.error(`Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` + `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`);
+}
+function noteLocalPinRename(from, to) {
+  console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
+}
+function getHmyRootDir() {
+  return join2(homedir(), CONFIG_DIR_NAME);
+}
 function getConfigDir() {
-  return join2(homedir(), ".harmony-mcp");
+  return join2(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+function getLegacyConfigDir() {
+  return join2(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 function getConfigPath() {
   return join2(getConfigDir(), "config.json");
 }
+function getLegacyConfigPath() {
+  return join2(getLegacyConfigDir(), "config.json");
+}
 function getLocalConfigPath(cwd) {
   return join2(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
@@ -36,9 +60,14 @@ function findLocalConfigPath(cwd) {
   const { root } = parse(dir);
   for (;; ) {
     if (dir !== home && dir !== root) {
-      const candidate = join2(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync2(candidate))
-        return candidate;
+      const current = join2(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync2(current))
+        return current;
+      const legacy = join2(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync2(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir)
@@ -61,9 +90,12 @@ function emptyConfig() {
   };
 }
 function loadConfig() {
-  const configPath = getConfigPath();
+  let configPath = getConfigPath();
   if (!existsSync2(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync2(configPath))
+      return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
   try {
     const data = readFileSync2(configPath, "utf-8");
@@ -113,7 +145,11 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath ? join2(dirname(foundPath), LOCAL_CONFIG_FILENAME) : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -125,6 +161,7 @@ function saveLocalConfig(config, cwd) {
   if (newConfig.projectId)
     cleanConfig.projectId = newConfig.projectId;
   writeFileSync2(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
@@ -259,7 +296,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join2(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
 var init_config = () => {};
 
 // src/prompt-builder.ts
@@ -5476,7 +5513,7 @@ var TOOLS = {
     }
   },
   harmony_update_agent_progress: {
-    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
+    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live. `sessionStale: true` means it opened one IN PLACE OF a session the inactivity sweep had closed (card #1067): nobody stopped you and the new row keeps the old one's steering channel and driver, so carry on — but the id changed, so poll harmony_get_pending_messages with the new `session.id` from this reply, not the one you were holding. `liveSessionIdChanged: true` is the weaker cousin: the live session is simply not the one you started, so use the new id, but do NOT assume steering survived — read `instruction`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7437,6 +7474,32 @@ ${options}
       if (result.session === null) {
         untrack(cardId, deps.getScopeId?.());
       }
+      const scopeId = deps.getScopeId?.();
+      const ownSession = memSession && memSession.scopeId === scopeId ? memSession : undefined;
+      const knownSessionId = ownSession?.agentSessionId;
+      const liveSessionId = result.session?.id;
+      const idChangedUnderUs = knownSessionId !== undefined && liveSessionId !== undefined && liveSessionId !== knownSessionId;
+      if (idChangedUnderUs && ownSession && liveSessionId) {
+        ownSession.agentSessionId = liveSessionId;
+      }
+      const newSessionId = liveSessionId ? ` (${liveSessionId})` : "";
+      if (result.sessionStale) {
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          instruction: "Your previous session had gone stale, so this report opened a new one in its place — nobody stopped you, and it kept the steering channel and driver of the run it replaced. Do NOT abandon the work. Poll harmony_get_pending_messages with the NEW session id" + newSessionId + ", not the one you were holding."
+        };
+      }
+      if (idChangedUnderUs) {
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          liveSessionIdChanged: true,
+          instruction: "The live session on this card is no longer the one you started — it may have been reopened, or deliberately ended and replaced. Nobody stopped you, so carry on, but poll harmony_get_pending_messages with the session id from this reply" + newSessionId + ". If steering matters to this run, do not assume it survived: start a session deliberately with harmony_start_agent_session and steerable: true."
+        };
+      }
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {

package/dist/lib/api-client.js

@@ -18,12 +18,40 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
+function resetLegacyNoticesForTest() {
+  warnedLegacyConfigDir = false;
+  warnedLegacyLocalPin = false;
+}
+function noteLegacyConfigDir(path) {
+  if (warnedLegacyConfigDir)
+    return;
+  warnedLegacyConfigDir = true;
+  console.error(`Harmony: reading the pre-#1082 config at ${path}. ` + `The current location is ${getConfigPath()}; ` + `run the agent daemon once to migrate, or move the file yourself.`);
+}
+function noteLegacyLocalPin(path) {
+  if (warnedLegacyLocalPin)
+    return;
+  warnedLegacyLocalPin = true;
+  console.error(`Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` + `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`);
+}
+function noteLocalPinRename(from, to) {
+  console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
+}
+function getHmyRootDir() {
+  return join(homedir(), CONFIG_DIR_NAME);
+}
 function getConfigDir() {
-  return join(homedir(), ".harmony-mcp");
+  return join(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+function getLegacyConfigDir() {
+  return join(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
+function getLegacyConfigPath() {
+  return join(getLegacyConfigDir(), "config.json");
+}
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
@@ -33,9 +61,14 @@ function findLocalConfigPath(cwd) {
   const { root } = parse(dir);
   for (;; ) {
     if (dir !== home && dir !== root) {
-      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync(candidate))
-        return candidate;
+      const current = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(current))
+        return current;
+      const legacy = join(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir)
@@ -58,9 +91,12 @@ function emptyConfig() {
   };
 }
 function loadConfig() {
-  const configPath = getConfigPath();
+  let configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync(configPath))
+      return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
   try {
     const data = readFileSync(configPath, "utf-8");
@@ -110,7 +146,11 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath ? join(dirname(foundPath), LOCAL_CONFIG_FILENAME) : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -122,6 +162,7 @@ function saveLocalConfig(config, cwd) {
   if (newConfig.projectId)
     cleanConfig.projectId = newConfig.projectId;
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
@@ -259,7 +300,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
 var init_config = () => {};
 
 // src/oauth-login.ts

package/dist/lib/config.js

@@ -18,12 +18,40 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
+function resetLegacyNoticesForTest() {
+  warnedLegacyConfigDir = false;
+  warnedLegacyLocalPin = false;
+}
+function noteLegacyConfigDir(path) {
+  if (warnedLegacyConfigDir)
+    return;
+  warnedLegacyConfigDir = true;
+  console.error(`Harmony: reading the pre-#1082 config at ${path}. ` + `The current location is ${getConfigPath()}; ` + `run the agent daemon once to migrate, or move the file yourself.`);
+}
+function noteLegacyLocalPin(path) {
+  if (warnedLegacyLocalPin)
+    return;
+  warnedLegacyLocalPin = true;
+  console.error(`Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` + `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`);
+}
+function noteLocalPinRename(from, to) {
+  console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
+}
+function getHmyRootDir() {
+  return join(homedir(), CONFIG_DIR_NAME);
+}
 function getConfigDir() {
-  return join(homedir(), ".harmony-mcp");
+  return join(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+function getLegacyConfigDir() {
+  return join(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
+function getLegacyConfigPath() {
+  return join(getLegacyConfigDir(), "config.json");
+}
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
@@ -33,9 +61,14 @@ function findLocalConfigPath(cwd) {
   const { root } = parse(dir);
   for (;; ) {
     if (dir !== home && dir !== root) {
-      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync(candidate))
-        return candidate;
+      const current = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(current))
+        return current;
+      const legacy = join(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir)
@@ -58,9 +91,12 @@ function emptyConfig() {
   };
 }
 function loadConfig() {
-  const configPath = getConfigPath();
+  let configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync(configPath))
+      return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
   try {
     const data = readFileSync(configPath, "utf-8");
@@ -110,7 +146,11 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath ? join(dirname(foundPath), LOCAL_CONFIG_FILENAME) : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -122,6 +162,7 @@ function saveLocalConfig(config, cwd) {
   if (newConfig.projectId)
     cleanConfig.projectId = newConfig.projectId;
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
@@ -259,7 +300,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
 var init_config = () => {};
 init_config();
 
@@ -269,6 +310,8 @@ export {
   setActiveContext,
   saveLocalConfig,
   saveConfig,
+  resetLegacyNoticesForTest,
+  noteLegacyLocalPin,
   loadLocalConfig,
   loadConfig,
   isConfigured,
@@ -277,6 +320,9 @@ export {
   getUserEmail,
   getMemoryDir,
   getLocalConfigPath,
+  getLegacyConfigPath,
+  getLegacyConfigDir,
+  getHmyRootDir,
   getConfigPath,
   getConfigDir,
   getApiUrl,
@@ -287,5 +333,6 @@ export {
   getActiveContext,
   findLocalConfigPath,
   describeActiveContext,
-  areSkillsInstalled
+  areSkillsInstalled,
+  LEGACY_LOCAL_CONFIG_FILENAME
 };

package/dist/lib/oauth-refresh.js

@@ -18,12 +18,40 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
+function resetLegacyNoticesForTest() {
+  warnedLegacyConfigDir = false;
+  warnedLegacyLocalPin = false;
+}
+function noteLegacyConfigDir(path) {
+  if (warnedLegacyConfigDir)
+    return;
+  warnedLegacyConfigDir = true;
+  console.error(`Harmony: reading the pre-#1082 config at ${path}. ` + `The current location is ${getConfigPath()}; ` + `run the agent daemon once to migrate, or move the file yourself.`);
+}
+function noteLegacyLocalPin(path) {
+  if (warnedLegacyLocalPin)
+    return;
+  warnedLegacyLocalPin = true;
+  console.error(`Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` + `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`);
+}
+function noteLocalPinRename(from, to) {
+  console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
+}
+function getHmyRootDir() {
+  return join(homedir(), CONFIG_DIR_NAME);
+}
 function getConfigDir() {
-  return join(homedir(), ".harmony-mcp");
+  return join(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+function getLegacyConfigDir() {
+  return join(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
+function getLegacyConfigPath() {
+  return join(getLegacyConfigDir(), "config.json");
+}
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
@@ -33,9 +61,14 @@ function findLocalConfigPath(cwd) {
   const { root } = parse(dir);
   for (;; ) {
     if (dir !== home && dir !== root) {
-      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync(candidate))
-        return candidate;
+      const current = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(current))
+        return current;
+      const legacy = join(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir)
@@ -58,9 +91,12 @@ function emptyConfig() {
   };
 }
 function loadConfig() {
-  const configPath = getConfigPath();
+  let configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync(configPath))
+      return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
   try {
     const data = readFileSync(configPath, "utf-8");
@@ -110,7 +146,11 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath ? join(dirname(foundPath), LOCAL_CONFIG_FILENAME) : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -122,6 +162,7 @@ function saveLocalConfig(config, cwd) {
   if (newConfig.projectId)
     cleanConfig.projectId = newConfig.projectId;
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
@@ -259,7 +300,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
 var init_config = () => {};
 
 // src/oauth-login.ts

package/dist/run-hook-cli.js

@@ -377,6 +377,7 @@ var SENSITIVE_SEGMENTS = [
   ".gemini",
   ".docker",
   ".kube",
+  ".hmy",
   ".harmony-mcp",
   ".password-store",
   ".claude",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "3.4.1",
+  "version": "3.6.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1335,6 +1335,23 @@ export class HarmonyApiClient {
     stopReason?: "human_stopped";
     /** How to legitimately work this card again (an explicit start). */
     recovery?: string;
+    /**
+     * This write REPLACED a session the silence sweep had closed (#1067): the
+     * returned session is a new row under a new id, carrying forward the
+     * `steerable`/`driver` of the one it replaced. Not a stop — the run
+     * continues — but every later poll must use the NEW `session.id`.
+     *
+     * Same word `getPendingMessages` answers with, deliberately: one flag name
+     * for one fact across both calls. Absent on an ordinary update, on a
+     * deliberate start, and from a pre-#1067 server.
+     */
+    sessionStale?: boolean;
+    /**
+     * The swept session that was replaced — never the new one's id. Present
+     * exactly when `sessionStale` is, so it is also the discriminator between
+     * the server's own verdict and the MCP tool's weaker `liveSessionIdChanged`.
+     */
+    replacedSessionId?: string;
   }> {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }

package/src/config.ts

@@ -22,7 +22,7 @@ export interface HarmonyConfig {
 }
 
 /**
- * Local project-level config (stored in .harmony-mcp.json in project root).
+ * Local project-level config (stored in .hmy.json in project root).
  * Only contains context IDs - API key stays global for security.
  */
 export interface LocalConfig {
@@ -31,22 +31,131 @@ export interface LocalConfig {
 }
 
 const DEFAULT_API_URL = "https://app.gethmy.com/api";
-const LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
 
+/**
+ * The config surface was renamed to `hmy` in card #1082 — `.harmony-mcp.json`
+ * became `.hmy.json`, and the home directory `~/.harmony-mcp/` became
+ * `~/.hmy/agent/`.
+ *
+ * `~/.hmy` already existed and belongs to the skill auto-update layer
+ * (`config.yaml`, `VERSION`, `bin/`, see `hmy-config.ts`), so the daemon's own
+ * state took the `agent/` subdirectory rather than landing a second file named
+ * `config.*` — in a different format, with a different owner — beside it.
+ *
+ * **Writes always go to the new name; reads fall back to the old one.**
+ * `@gethmy/mcp` and `@gethmy/agent` are published and the daemon runs from a
+ * frozen npx cache, so a hard cut would leave a running daemon unable to find
+ * its config until a coordinated release. `migrateConfigDir` (harmony-agent)
+ * moves the data once, at daemon startup, which makes the fallback moot in
+ * practice — it stays only for a client that never runs the daemon.
+ *
+ * The legacy spellings are exported because two things still need them after
+ * the fallback is removed: the migration, and the harness read-denylists. The
+ * old directory keeps holding an API key and 3430 run logs until an operator
+ * deletes it, so denying only the new name would OPEN it. See
+ * `credentialDirectories()` in harmony-harness and `HARNESS_CREDENTIAL_LEAVES`
+ * in `run-redaction.ts`; both name old and new.
+ */
+const LOCAL_CONFIG_FILENAME = ".hmy.json";
+export const LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+const CONFIG_DIR_NAME = ".hmy";
+const CONFIG_DIR_SUBDIR = "agent";
+const LEGACY_CONFIG_DIR_NAME = ".harmony-mcp";
+
+/**
+ * Fallbacks announce themselves ONCE per process (#1082).
+ *
+ * A silent fallback is the failure mode this whole compatibility window is
+ * exposed to: an operator whose migration failed, or whose daemon runs from a
+ * frozen npx cache, gets no signal that they still depend on a path scheduled
+ * for removal — and then the follow-up card that deletes the fallback breaks
+ * them with nothing in any log to connect the two.
+ *
+ * Latched per process rather than per call because these sit on hot paths —
+ * `loadConfig` runs on every tool dispatch — and a line repeated hundreds of
+ * times is read as noise and filtered out, which is the same as silence.
+ *
+ * `console.error`, not `console.log`: on stdio transport stdout carries the
+ * JSON-RPC protocol, so anything printed there corrupts the session. Same
+ * convention as `skills.ts`.
+ */
+let warnedLegacyConfigDir = false;
+let warnedLegacyLocalPin = false;
+
+/**
+ * Clear both latches. Tests only.
+ *
+ * A per-process latch is not observable twice, so without this the "said once"
+ * half of the contract is untestable — and an untested notice is how the
+ * fallback goes silent again without anyone noticing. Exported deliberately
+ * rather than left to a test reaching into module state.
+ */
+export function resetLegacyNoticesForTest(): void {
+  warnedLegacyConfigDir = false;
+  warnedLegacyLocalPin = false;
+}
+
+function noteLegacyConfigDir(path: string): void {
+  if (warnedLegacyConfigDir) return;
+  warnedLegacyConfigDir = true;
+  console.error(
+    `Harmony: reading the pre-#1082 config at ${path}. ` +
+      `The current location is ${getConfigPath()}; ` +
+      `run the agent daemon once to migrate, or move the file yourself.`,
+  );
+}
+
+/** Said once when a repo pin is read under the old name. */
+export function noteLegacyLocalPin(path: string): void {
+  if (warnedLegacyLocalPin) return;
+  warnedLegacyLocalPin = true;
+  console.error(
+    `Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` +
+      `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`,
+  );
+}
+
+/** Said once when a write moves the pin to the current name. */
+function noteLocalPinRename(from: string, to: string): void {
+  console.error(
+    `Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`,
+  );
+}
+
+/**
+ * `~/.hmy` — the root the whole `hmy` surface shares. Named separately from
+ * `getConfigDir()` because the denylists want the WHOLE tree, not just the
+ * daemon's corner of it: `config.yaml` is not a credential, but a future
+ * sibling might be, and a directory has no spellings to enumerate.
+ */
+export function getHmyRootDir(): string {
+  return join(homedir(), CONFIG_DIR_NAME);
+}
+
+/** `~/.hmy/agent` — where every writer writes. Never falls back. */
 export function getConfigDir(): string {
-  return join(homedir(), ".harmony-mcp");
+  return join(getHmyRootDir(), CONFIG_DIR_SUBDIR);
+}
+
+/** `~/.harmony-mcp` — the pre-#1082 location. Read-only, and denied forever. */
+export function getLegacyConfigDir(): string {
+  return join(homedir(), LEGACY_CONFIG_DIR_NAME);
 }
 
 export function getConfigPath(): string {
   return join(getConfigDir(), "config.json");
 }
 
+export function getLegacyConfigPath(): string {
+  return join(getLegacyConfigDir(), "config.json");
+}
+
 export function getLocalConfigPath(cwd?: string): string {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
 
 /**
- * Find the nearest `.harmony-mcp.json` at or above `cwd` (card #893).
+ * Find the nearest `.hmy.json` at or above `cwd` (card #893).
  *
  * The old behaviour looked in the exact cwd and nowhere else, so a server
  * started from a package directory or a git worktree never saw the repo's pin
@@ -56,9 +165,15 @@ export function getLocalConfigPath(cwd?: string): string {
  * Two directories are deliberately skipped, however deep the walk goes:
  *
  * - **the home directory** — a stray file there would capture every session in
- *   every repo, and `~/.harmony-mcp/config.json` is already the global pin;
+ *   every repo, and `~/.hmy/agent/config.json` is already the global pin;
  * - **the filesystem root** — same reasoning, machine-wide.
  *
+ * **Both names are checked in the SAME directory before walking up** (#1082),
+ * which is the only ordering that preserves #893. Checking every ancestor for
+ * `.hmy.json` first and only then re-walking for `.harmony-mcp.json` would let
+ * a parent repo's new-name pin beat the current repo's own legacy pin — the
+ * nearest file must win whichever name it carries.
+ *
  * Returns `null` when no ancestor carries one.
  */
 export function findLocalConfigPath(cwd?: string): string | null {
@@ -68,8 +183,13 @@ export function findLocalConfigPath(cwd?: string): string | null {
 
   for (;;) {
     if (dir !== home && dir !== root) {
-      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
-      if (existsSync(candidate)) return candidate;
+      const current = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(current)) return current;
+      const legacy = join(dir, LEGACY_LOCAL_CONFIG_FILENAME);
+      if (existsSync(legacy)) {
+        noteLegacyLocalPin(legacy);
+        return legacy;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir) return null;
@@ -93,10 +213,14 @@ function emptyConfig(): HarmonyConfig {
 }
 
 export function loadConfig(): HarmonyConfig {
-  const configPath = getConfigPath();
-
+  // Read the new location, fall back to the pre-#1082 one. The fallback is
+  // read-only on purpose: `saveConfig` always writes the new path, so the first
+  // write after an upgrade lands there and the old file stops being consulted.
+  let configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return emptyConfig();
+    configPath = getLegacyConfigPath();
+    if (!existsSync(configPath)) return emptyConfig();
+    noteLegacyConfigDir(configPath);
   }
 
   try {
@@ -157,14 +281,33 @@ export function loadLocalConfig(cwd?: string): LocalConfig | null {
   }
 }
 
+/** Returns the path actually written, which is NOT always `<cwd>/.hmy.json`. */
 export function saveLocalConfig(
   config: Partial<LocalConfig>,
   cwd?: string,
-): void {
-  // Write back to the file we READ, not to the cwd: a `set_project_context`
-  // issued from a package directory must update the repo's pin rather than
-  // strand a second config file the repo root never looks at (card #893).
-  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
+): string {
+  // Write back to the DIRECTORY we read from, under the CURRENT name (#893,
+  // #1082). #893's rule is about the directory: a `set_project_context` issued
+  // from a package subdirectory must update the repo's pin rather than strand a
+  // second config file the repo root never looks at. The filename was never the
+  // point, and writing back to `.harmony-mcp.json` because that is what the read
+  // found would make this the one writer still creating the old name — the
+  // thing #1082 exists to stop, and a live trap for the card that removes the
+  // read fallback, since a pin left under the old name goes invisible and the
+  // session falls through to the global context. That silent wrong-workspace
+  // failure is exactly what #893 was filed to remove.
+  //
+  // The legacy file is left on disk rather than deleted, matching
+  // `migrateConfigDir`'s doctrine: this code removes nothing an operator wrote.
+  // It is inert from the next read on — `findLocalConfigPath` prefers
+  // `.hmy.json` in the same directory — and `noteLocalPinRename` says so once.
+  const foundPath = findLocalConfigPath(cwd);
+  const localConfigPath = foundPath
+    ? join(dirname(foundPath), LOCAL_CONFIG_FILENAME)
+    : getLocalConfigPath(cwd);
+  if (foundPath !== null && foundPath !== localConfigPath) {
+    noteLocalPinRename(foundPath, localConfigPath);
+  }
 
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
@@ -178,6 +321,7 @@ export function saveLocalConfig(
   if (newConfig.projectId) cleanConfig.projectId = newConfig.projectId;
 
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  return localConfigPath;
 }
 
 export function hasLocalConfig(cwd?: string): boolean {
@@ -222,10 +366,10 @@ export function setUserEmail(email: string | null): void {
 }
 
 export interface SetContextOptions {
-  /** Force a write to the repo-local `.harmony-mcp.json` (creating it). */
+  /** Force a write to the repo-local `.hmy.json` (creating it). */
   local?: boolean;
   /**
-   * Force a write to the global `~/.harmony-mcp/config.json`, even when a local
+   * Force a write to the global `~/.hmy/agent/config.json`, even when a local
    * file exists. Setup uses this to mirror the chosen context into the global
    * default; without it the mirror would land back in the local file it just
    * wrote, leaving every server started from another directory with no context.
@@ -318,7 +462,7 @@ export function setActiveWorkspace(
 /**
  * The active pair, read from ONE source (card #893).
  *
- * A local `.harmony-mcp.json` wins **as a whole file**, not field by field. The
+ * A local `.hmy.json` wins **as a whole file**, not field by field. The
  * two ids used to fall back to the global config independently, which quietly
  * re-created the very mismatch this card removes: `saveLocalConfig` omits null
  * values, so writing `projectId: null` locally did not clear the project — it

package/src/hook-install.ts

@@ -12,7 +12,7 @@
  * `hooks` is not merely missing from that list — it is the key that BROKE the
  * previous denylist and forced the inversion. A hook block in a run's own
  * worktree executed as the daemon user, outside the sandbox, and read
- * `~/.ssh/config` and `~/.harmony-mcp/config.json`. So writing this hook into a
+ * `~/.ssh/config` and `~/.hmy/agent/config.json`. So writing this hook into a
  * project settings file would throw `ProjectSandboxOverrideError` on every
  * contained implement run in that repo — it would not degrade, it would stop
  * the daemon.

package/src/oauth-refresh.ts

@@ -33,7 +33,7 @@ interface RefreshResponse {
 let inFlight: Promise<string | null> | null = null;
 
 // Cross-process serialization. Every Claude Code session spawns its own stdio
-// MCP process, and they all share ~/.harmony-mcp/config.json. The refresh
+// MCP process, and they all share ~/.hmy/agent/config.json. The refresh
 // token rotates on use, so two processes refreshing concurrently would each
 // POST a refresh: the first consumes the token, the second replays a now-
 // consumed token and trips the server's reuse detection, revoking the whole

package/src/run-redaction.ts

@@ -65,8 +65,15 @@ export type WithholdReason = "sensitive-path";
  * whole segment is sensitive regardless of the file name inside it.
  *
  * Kept in step with `credentialDirectories()` in the harness — see the module
- * doc. `.harmony-mcp` is here for the same reason it is first there: it holds
- * this product's own API key.
+ * doc. `.hmy` is here for the same reason it is first there: it holds this
+ * product's own API key. `.harmony-mcp` is its pre-#1082 name and stays listed
+ * FOREVER — the rename moved the daemon's writes, not the operator's old
+ * directory, which keeps that key on disk until they delete it by hand.
+ *
+ * One segment covers `~/.hmy/agent` and every future sibling: the match below
+ * walks segments, so `.hmy` needs no `CONFIG_SCOPED_SEGMENTS` special case.
+ * Both names are dot-prefixed and product-specific, so neither can collide with
+ * a source directory the way the bare `gh` / `op` entries could.
  */
 const SENSITIVE_SEGMENTS: readonly string[] = [
   ".ssh",
@@ -76,6 +83,7 @@ const SENSITIVE_SEGMENTS: readonly string[] = [
   ".gemini",
   ".docker",
   ".kube",
+  ".hmy",
   ".harmony-mcp",
   ".password-store",
   // `~/.claude` holds `.credentials.json`, Claude Code's own OAuth token, and
@@ -125,7 +133,21 @@ export const HARNESS_CREDENTIAL_LEAVES: readonly {
    */
   readonly kind: "dir" | "file";
 }[] = [
-  { path: ".harmony-mcp", kind: "dir" }, // getConfigDir()
+  // Three entries for one credential directory (#1082). `~/.harmony-mcp` was
+  // renamed to `~/.hmy/agent`, and this list does NOT follow `getConfigDir()` —
+  // it is hand-transcribed, so a rename here is a decision rather than a
+  // consequence. The decision is to ADD, never to swap: an operator's
+  // `~/.harmony-mcp` keeps its `config.json` (the Harmony API key) and its run
+  // logs until they delete it by hand, so dropping the old name would put the
+  // key back on the board.
+  //
+  // `.hmy` covers the whole tree, which is what `isSensitivePath` wants: it
+  // matches on path SEGMENTS, so a single segment needs no `CONFIG_SCOPED_
+  // SEGMENTS` special case the way `.config/gh` does. `.hmy/agent` is listed
+  // beside it so the mirror test walks the exact path the harness names.
+  { path: ".hmy", kind: "dir" }, // getHmyRootDir()
+  { path: ".hmy/agent", kind: "dir" }, // getConfigDir()
+  { path: ".harmony-mcp", kind: "dir" }, // getLegacyConfigDir()
   { path: ".claude", kind: "dir" },
   { path: ".claude.json", kind: "file" },
   { path: ".ssh", kind: "dir" },

package/src/run-state.ts

@@ -14,7 +14,7 @@
  * server's memory, so the session identity has to travel **through the
  * filesystem**. That is what this module is.
  *
- * ## Why not `~/.harmony-mcp/`
+ * ## Why not `~/.hmy/agent/`
  *
  * `getConfigDir()` is the FIRST entry of `credentialDirectories()`
  * (`packages/harmony-harness/src/run-containment.ts`) and is read-denied to

package/src/server.ts

@@ -1610,7 +1610,7 @@ export const TOOLS = {
   },
   harmony_update_agent_progress: {
     description:
-      "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
+      "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live. `sessionStale: true` means it opened one IN PLACE OF a session the inactivity sweep had closed (card #1067): nobody stopped you and the new row keeps the old one's steering channel and driver, so carry on — but the id changed, so poll harmony_get_pending_messages with the new `session.id` from this reply, not the one you were holding. `liveSessionIdChanged: true` is the weaker cousin: the live session is simply not the one you started, so use the new id, but do NOT assume steering survived — read `instruction`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3293,7 +3293,7 @@ export async function handleToolCall(
           // deliberately-set active project is a hard scope: `found` there means
           // the card was already in it, so there is nothing to change — and we
           // never let a read silently repoint a context the user chose (which,
-          // on the local stdio MCP, persists to ~/.harmony-mcp/config.json
+          // on the local stdio MCP, persists to ~/.hmy/agent/config.json
           // across sessions). Confirm the target back either way so a
           // wrong-context resolve is visible immediately.
           const established = activeProjectId == null;
@@ -4379,6 +4379,77 @@ export async function handleToolCall(
         untrack(cardId, deps.getScopeId?.());
       }
 
+      // Two DIFFERENT facts, and the earlier cut of #1067 merged them into one
+      // sentence that was false in three reachable cases.
+      //
+      // `result.sessionStale` is the server's own verdict: it replaced a
+      // recently-swept session AND carried its `steerable`/`driver` forward. Only
+      // that verdict licenses saying the steering channel survived.
+      //
+      // The id comparison establishes strictly less — that the live session is
+      // not the one this run recorded at start. It catches the case the flag
+      // cannot: `flushMemoryActions` is fire-and-forget, sends
+      // `implicitCreate: true` and discards its result, so when the sweep has
+      // closed the row that bookkeeping write is what mints the replacement and
+      // consumes the server's one `sessionStale`; this checkpoint then lands on a
+      // live row under a new id with `created: false`. But an id change alone is
+      // ALSO what `harmony_move_card` leaves behind — it ends the session and
+      // untracks the card without calling `cleanupMemorySession`, so the recorded
+      // id outlives a deliberate `completed` end — and what a lapsed recency
+      // window leaves behind, where the new row genuinely is NOT steerable.
+      // Claiming inheritance there tells a run its steering survived when it
+      // did not, which suppresses the one recovery that works (an explicit
+      // `harmony_start_agent_session` with `steerable: true`). Worse than
+      // silence, so the two paths say different things.
+      //
+      // The RESYNC is unconditional and is a fix in its own right: this field
+      // scopes working-memory writes (`sessionScopeFor`) and feeds comment
+      // attribution, so a stale id there is wrong regardless of what is reported.
+      const scopeId = deps.getScopeId?.();
+      // `memorySessions` is keyed by card id ALONE at module scope, so on the
+      // hosted transport a lookup can hand back another user's session for the
+      // same card. Anything that CLAIMS the tracked session compares the scope
+      // first — `chooseCommentSession` does, and #1035 is why.
+      const ownSession =
+        memSession && memSession.scopeId === scopeId ? memSession : undefined;
+      const knownSessionId = ownSession?.agentSessionId;
+      const liveSessionId = (result.session as { id?: string } | null)?.id;
+      const idChangedUnderUs =
+        knownSessionId !== undefined &&
+        liveSessionId !== undefined &&
+        liveSessionId !== knownSessionId;
+      // Report once: the run now knows this id, so a later checkpoint on the
+      // same session is silent again rather than crying change forever.
+      if (idChangedUnderUs && ownSession && liveSessionId) {
+        ownSession.agentSessionId = liveSessionId;
+      }
+      const newSessionId = liveSessionId ? ` (${liveSessionId})` : "";
+      if (result.sessionStale) {
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          instruction:
+            "Your previous session had gone stale, so this report opened a new one in its place — nobody stopped you, and it kept the steering channel and driver of the run it replaced. Do NOT abandon the work. Poll harmony_get_pending_messages with the NEW session id" +
+            newSessionId +
+            ", not the one you were holding.",
+        };
+      }
+      if (idChangedUnderUs) {
+        // Everything this branch knows, and nothing it does not: no claim that
+        // anything went stale, and none that any capability was preserved.
+        return {
+          success: true,
+          midSessionLearnings: 0,
+          ...result,
+          liveSessionIdChanged: true,
+          instruction:
+            "The live session on this card is no longer the one you started — it may have been reopened, or deliberately ended and replaced. Nobody stopped you, so carry on, but poll harmony_get_pending_messages with the session id from this reply" +
+            newSessionId +
+            ". If steering matters to this run, do not assume it survived: start a session deliberately with harmony_start_agent_session and steerable: true.",
+        };
+      }
+
       // Phase 0 (memory architecture v2): mid-session learning extraction removed.
       return { success: true, midSessionLearnings: 0, ...result };
     }

package/src/tui/setup.ts

@@ -1552,6 +1552,9 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     }
   }
 
+  /** Set once step 9 writes the repo pin, so the summary names the real file. */
+  let writtenLocalConfigPath: string | null = null;
+
   // Step 9: Save context \u2014 both local (cwd-scoped) and global (user default).
   // Local config only resolves when the server runs with this repo as cwd;
   // remote/OAuth connections and other cwds fall back to the global active
@@ -1562,9 +1565,15 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     const localConfig: { workspaceId?: string; projectId?: string } = {};
     if (selectedWorkspaceId) localConfig.workspaceId = selectedWorkspaceId;
     if (selectedProjectId) localConfig.projectId = selectedProjectId;
-    saveLocalConfig(localConfig, cwd);
+    // Print the path `saveLocalConfig` ACTUALLY wrote, not a re-derived guess
+    // (#1082). `getLocalConfigPath` is `<cwd>/.hmy.json` with no upward walk,
+    // while the write targets the directory of the pin already in scope — which
+    // may be an ancestor (#893). Run setup from `packages/foo` in a repo pinned
+    // at its root and the two disagree, so this line reported a file that does
+    // not exist. Returning the path is what removes the second derivation.
+    writtenLocalConfigPath = saveLocalConfig(localConfig, cwd);
     console.log(
-      `  ${colors.success("\u2713")} ${colors.dim(formatPath(getLocalConfigPath(cwd), home))} ${colors.dim("(created)")}`,
+      `  ${colors.success("\u2713")} ${colors.dim(formatPath(writtenLocalConfigPath, home))} ${colors.dim("(created)")}`,
     );
 
     // Mirror the choice into the GLOBAL default, explicitly (#893). The local
@@ -1629,7 +1638,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     }
     if (selectedWorkspaceId || selectedProjectId) {
       console.log(
-        `    Context:   ${formatPath(getLocalConfigPath(cwd), home)}`,
+        `    Context:   ${formatPath(writtenLocalConfigPath ?? getLocalConfigPath(cwd), home)}`,
       );
     }
 

package/src/tui/writer.ts

@@ -33,6 +33,16 @@ function ensureDir(dirPath: string): void {
   }
 }
 
+/**
+ * Path fragments that mark a file as living in a Harmony config directory, and
+ * therefore as 0o600 rather than 0o644.
+ *
+ * `.hmy` covers `~/.hmy/agent/config.json` and the repo-local `.hmy.json` in one
+ * fragment. `.harmony-mcp` is the pre-#1082 spelling of both, kept so `setup`
+ * writing into an un-migrated directory still writes a private file.
+ */
+const CONFIG_DIR_MARKERS: readonly string[] = [".hmy", ".harmony-mcp"];
+
 /**
  * Write a file, optionally skipping if exists
  */
@@ -49,7 +59,17 @@ export function writeFile(
 
   try {
     ensureDir(dirname(filePath));
-    const defaultMode = filePath.includes(".harmony-mcp") ? 0o600 : 0o644;
+    // 0o600 for anything under a Harmony config directory — that is where the
+    // API key lives. BOTH names are tested (#1082): the rename to `~/.hmy`
+    // moved where setup writes, so matching the old name alone would have
+    // silently written the credential 0o644 (world-readable) at the new path,
+    // and nothing about a successful write would have said so. `setup` is also
+    // still able to write into a legacy directory that has not been migrated.
+    const defaultMode = CONFIG_DIR_MARKERS.some((marker) =>
+      filePath.includes(marker),
+    )
+      ? 0o600
+      : 0o644;
     const mode = options.mode ?? defaultMode;
     writeFileSync(filePath, content, { mode });
     if (options.mode !== undefined) {