@sechroom/cli 2026.9.1 → 2026.9.2

package/dist/index.js

@@ -1234,7 +1234,7 @@ ${mem.text.trim()}`
   if (parts.length === 0) return null;
   return { body: parts.join("\n\n"), refs };
 }
-async function createOverride(cfg, template, personalWorkspaceId) {
+async function createOverride(cfg, template, personalWorkspaceId, source) {
   const client = await makeClient(cfg);
   const overrideTags = template.templateTags.filter(
     (t) => t !== "sechroom:role:template" && !t.startsWith("sechroom:bundle:") && !t.startsWith("sechroom:template-ref:")
@@ -1249,7 +1249,7 @@ async function createOverride(cfg, template, personalWorkspaceId) {
       type: "reference",
       content: "{}",
       confidence: 1,
-      source: "cli-agent-instructions-customize",
+      source,
       archetype: "Document",
       title: template.title ?? null,
       tags: overrideTags,
@@ -7031,9 +7031,11 @@ function registerChannel(program2) {
         (typeof payload === "string" ? payload : JSON.stringify(payload)) + "\n"
       )
     );
+    const authExit = createAuthExpiredExit();
     const leaseHeartbeats = createChannelLeaseHeartbeatManager(
       cfg,
-      located.state.taskLeaseTtlSeconds ?? 120
+      located.state.taskLeaseTtlSeconds ?? 120,
+      { onAuthExpired: authExit.onAuthExpired }
     );
     const drain = createClaimDrain(cfg, instance.id, deliver, {
       onClaimed: leaseHeartbeats.onClaimed
@@ -7072,13 +7074,11 @@ function registerChannel(program2) {
         ) + style.dim("streaming matched events to stdout; Ctrl-C to stop.\n")
       );
     }
-    try {
-      await holdOpen(conn);
-    } finally {
-      stopReconciliation();
-      stopHeartbeat();
-      leaseHeartbeats.stop();
-    }
+    await holdChannelOpen(conn, authExit.released, [
+      stopReconciliation,
+      stopHeartbeat,
+      leaseHeartbeats.stop
+    ]);
   });
   channel.command("mcp").description(
     "Run as a Claude Code channel (local-stdio MCP server) \u2014 claim and push dispatched tasks into the session"
@@ -7101,9 +7101,11 @@ function registerChannel(program2) {
         params: { content, meta }
       });
     });
+    const authExit = createAuthExpiredExit();
     const leaseHeartbeats = createChannelLeaseHeartbeatManager(
       cfg,
-      located.state.taskLeaseTtlSeconds ?? 120
+      located.state.taskLeaseTtlSeconds ?? 120,
+      { onAuthExpired: authExit.onAuthExpired }
     );
     const drain = createClaimDrain(cfg, instance.id, deliver, {
       onClaimed: leaseHeartbeats.onClaimed
@@ -7129,13 +7131,16 @@ function registerChannel(program2) {
 `
       )
     );
-    try {
-      await holdOpen(conn);
-    } finally {
-      stopReconciliation();
-      stopHeartbeat();
-      leaseHeartbeats.stop();
-    }
+    await holdChannelOpen(conn, authExit.released, [
+      stopReconciliation,
+      stopHeartbeat,
+      leaseHeartbeats.stop,
+      // The stdio transport keeps a stdin `data` listener, which holds the event
+      // loop open for as long as the parent holds the pipe. Without this close, a
+      // `process.exitCode` set on the auth path never becomes an exit and the
+      // parent sees a connected-but-inert channel instead of a dead one.
+      () => mcp.close()
+    ]);
   });
   channel.command("install").description(
     "Wire `sechroom channel mcp` into the project .mcp.json as a Claude Code channel MCP server (idempotent)"
@@ -7239,6 +7244,7 @@ function startExecutorHeartbeat(refresh, intervalMilliseconds, dependencies = {}
 }
 var leaseHeartbeatApi = (cfg, path, init, deps = {}) => createAuthedRequest(cfg, deps)(path, init);
 function classifyLeaseHeartbeatFailure(error) {
+  if (error instanceof AuthExpiredError) return "auth";
   if (!(error instanceof HttpError)) return "retry";
   if (error.status === 408 || error.status === 429) return "retry";
   if (error.status < 400 || error.status >= 500) return "retry";
@@ -7246,6 +7252,10 @@ function classifyLeaseHeartbeatFailure(error) {
     return "released";
   return "terminal";
 }
+function authExpiredLine(error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return `auth expired \u2014 run \`sechroom login\` to re-authenticate: ${detail}`;
+}
 function leaseHeartbeatStoppedLine(leaseId, error) {
   if (!(error instanceof HttpError))
     return `lease heartbeat stopped for ${leaseId}: ${String(error)}`;
@@ -7288,6 +7298,10 @@ function startChannelTaskLeaseHeartbeat(cfg, claim, intervalMilliseconds = 3e4,
       if (disposition === "retry") throw error;
       stop?.();
       dependencies.onLeaseTerminal?.(leaseId, error);
+      if (disposition === "auth") {
+        dependencies.onAuthExpired?.(error);
+        return void 0;
+      }
       if (disposition === "terminal")
         onError(leaseHeartbeatStoppedLine(leaseId, error));
       return void 0;
@@ -7301,6 +7315,7 @@ function startChannelTaskLeaseHeartbeat(cfg, claim, intervalMilliseconds = 3e4,
 }
 function createChannelLeaseHeartbeatManager(cfg, taskLeaseTtlSeconds, dependencies = {}) {
   const stops = /* @__PURE__ */ new Map();
+  let authExpired = false;
   const intervalMilliseconds = Math.max(
     1e3,
     Math.min(3e4, Math.floor(taskLeaseTtlSeconds * 1e3 / 4))
@@ -7320,6 +7335,16 @@ function createChannelLeaseHeartbeatManager(cfg, taskLeaseTtlSeconds, dependenci
           // map does not accumulate stopped leases for the life of the channel.
           onLeaseTerminal: (id) => {
             stops.delete(id);
+          },
+          // A dead credential fails every lease at once, so N held leases would
+          // otherwise raise this N times in the same tick. Latch it: stop every beat
+          // (not just the one that noticed), then escalate exactly once.
+          onAuthExpired: (error) => {
+            if (authExpired) return;
+            authExpired = true;
+            for (const cancel of stops.values()) cancel();
+            stops.clear();
+            dependencies.onAuthExpired?.(error);
           }
         }
       );
@@ -7414,15 +7439,50 @@ async function openConnection(cfg, onEvent, executorInstanceId) {
   await conn.start();
   return conn;
 }
-function holdOpen(conn) {
+function holdOpen(conn, until) {
   return new Promise((resolve9) => {
     const stop = () => {
       void conn.stop().finally(resolve9);
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
+    void until?.then(stop);
   });
 }
+async function holdChannelOpen(conn, released, teardown) {
+  try {
+    await holdOpen(conn, released);
+  } finally {
+    let firstError;
+    let failed = false;
+    for (const step of teardown) {
+      try {
+        await step();
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          firstError = error;
+        }
+      }
+    }
+    if (failed) throw firstError;
+  }
+}
+function createAuthExpiredExit() {
+  let release;
+  const released = new Promise((resolve9) => {
+    release = resolve9;
+  });
+  return {
+    onAuthExpired: (error) => {
+      process.stderr.write(err(`${authExpiredLine(error)}
+`));
+      process.exitCode = 1;
+      release();
+    },
+    released
+  };
+}
 function parseEvent(payload) {
   let data = payload;
   if (typeof payload === "string") {
@@ -7477,92 +7537,6 @@ function str(v) {
   return typeof v === "string" ? v : v == null ? "" : String(v);
 }
 
-// src/commands/chat.ts
-function registerChat(program2) {
-  const chat = program2.command("chat").description("Send and read Slack / Discord channel messages").option("--surface <surface>", "slack | discord", "slack");
-  chat.addHelpText(
-    "after",
-    `
-Examples:
-  $ sechroom chat send C0123456789 "deploy is green" --surface slack
-  $ sechroom chat send 987654321098765432 "deploy is green" --surface discord --guild 123456789012345678
-  $ sechroom chat send C0123456789 "lgtm" --surface slack --as user --parent 1718049600.123456
-  $ sechroom chat messages --surface slack
-  $ sechroom chat replies 1718049600.123456 --surface slack
-  $ sechroom chat stop-tracking 1718049600.123456 --surface slack`
-  );
-  chat.command("send <channelId> <text>").description("Send a message to a channel (POST /chat/channel-messages/{surface})").option("--guild <guildId>", "Discord guild snowflake \u2014 required for --surface discord").option("--memory <memoryId>", "Attach a sechroom memory id").option("--no-track", "Don't capture replies to this message").option("--parent <parentMessage>", "Thread under a parent (Slack thread_ts / Discord message id)").option("--source <source>", "Source / lane stamp (renders an attribution footer)", "cli").option("--as <as>", "Slack only: 'bot' (default) or 'user' (your linked Slack identity)", "bot").action(async (channelId, text2, opts, cmd) => {
-    const { surface, ...globals } = cmd.optsWithGlobals();
-    const json = Boolean(cmd.optsWithGlobals().json);
-    const cfg = resolveConfig(globals);
-    const data = await runApi("Sending message", async () => {
-      const client = await makeClient(cfg);
-      return client.POST("/chat/channel-messages/{surface}", {
-        params: { path: { surface: String(surface) } },
-        body: {
-          channelId,
-          text: text2,
-          guildId: opts.guild ?? null,
-          attachedMemoryId: opts.memory ?? null,
-          trackReplies: opts.track,
-          parentMessage: opts.parent ?? null,
-          source: opts.source,
-          as: opts.as
-        }
-      });
-    });
-    if (!data.ok) {
-      if (json) {
-        emit(data, true);
-      } else {
-        process.stderr.write(
-          `${err("\u2717")} send failed: ${data.upstreamError ?? "error"}${data.errorDescription ? ` \u2014 ${data.errorDescription}` : ""}
-`
-        );
-      }
-      process.exit(1);
-    }
-    const idPart = data.persistedId ? ` ${style.dim(`(${data.persistedId})`)}` : "";
-    emitAction(`sent to ${surface} ${style.bold(channelId)}${idPart}`, data, json);
-  });
-  chat.command("messages").description("List recent channel messages (GET /chat/channel-messages/{surface})").action(async (_opts, cmd) => {
-    const { surface, ...globals } = cmd.optsWithGlobals();
-    const cfg = resolveConfig(globals);
-    const data = await runApi("Fetching messages", async () => {
-      const client = await makeClient(cfg);
-      return client.GET("/chat/channel-messages/{surface}", {
-        params: { path: { surface: String(surface) } }
-      });
-    });
-    emit(data, cmd.optsWithGlobals().json);
-  });
-  chat.command("replies <messageId>").description("List thread replies for a message (GET /chat/channel-messages/by-id/{id}/replies)").action(async (messageId, _opts, cmd) => {
-    const cfg = resolveConfig(cmd.optsWithGlobals());
-    const data = await runApi("Fetching replies", async () => {
-      const client = await makeClient(cfg);
-      return client.GET("/chat/channel-messages/by-id/{id}/replies", {
-        params: { path: { id: messageId } }
-      });
-    });
-    emit(data, cmd.optsWithGlobals().json);
-  });
-  chat.command("stop-tracking <messageId>").description("Stop watching a message for replies (POST .../by-id/{id}/stop-tracking-replies)").action(async (messageId, _opts, cmd) => {
-    const cfg = resolveConfig(cmd.optsWithGlobals());
-    const data = await runApi("Stopping reply tracking", async () => {
-      const client = await makeClient(cfg);
-      return client.POST("/chat/channel-messages/by-id/{id}/stop-tracking-replies", {
-        params: { path: { id: messageId } },
-        body: {}
-      });
-    });
-    emitAction(`stopped tracking replies on ${style.bold(messageId)}`, data, cmd.optsWithGlobals().json);
-  });
-}
-
-// src/commands/checkpoint.ts
-import { mkdirSync as mkdirSync15, writeFileSync as writeFileSync14 } from "fs";
-import { dirname as dirname14, join as join17 } from "path";
-
 // src/commands/hook.ts
 import { createHash as createHash4 } from "crypto";
 import { existsSync as existsSync12, mkdirSync as mkdirSync14, readFileSync as readFileSync12, statSync as statSync4, writeFileSync as writeFileSync13 } from "fs";
@@ -8160,6 +8134,17 @@ function resolveLane(flagLane, cwd) {
   if (!base) return void 0;
   return applyWorktreeLaneSuffix(base, start);
 }
+function resolveSourceLane(explicit, cwd) {
+  const trimmed = explicit?.trim();
+  if (trimmed) return trimmed;
+  const lane = resolveLane(void 0, cwd);
+  if (!lane) {
+    throw new Error(
+      "no --source and no lane pinned for this checkout \u2014 a record's source must name the lane that wrote it, never a generic value. Pin one with `sechroom lane set --code-lane <id>` (see `sechroom lane`), set SECHROOM_LANE, or pass --source explicitly."
+    );
+  }
+  return lane;
+}
 var INTENT_FILE = join16(".sechroom", "continuity.json");
 var LOCAL_DRY_RUN_VALIDATION_WARNING = "LOCAL-ONLY \u2014 NOT SERVER-VALIDATED";
 function resolveIntentPath(start) {
@@ -8196,6 +8181,56 @@ function localDryRunMissingFields(i) {
   ];
   return required.filter(([key]) => !String(i[key] ?? "").trim()).map(([, flag]) => flag);
 }
+var SNAPSHOT_LIMITS = {
+  /** objective / state / lastAction / nextAction / resumeInstruction. */
+  bodyFieldLength: 2e3,
+  /** Any single entry in constraints / questions / surfaceMarkers / artifacts. */
+  listItemLength: 500,
+  /** Entries per list. */
+  listLength: 25
+};
+function snapshotLimitViolations(i) {
+  const violations = [];
+  const bodyFields = [
+    "objective",
+    "state",
+    "lastAction",
+    "nextAction",
+    "resumeInstruction"
+  ];
+  for (const key of bodyFields) {
+    const value = i[key];
+    if (typeof value !== "string") continue;
+    if (value.length > SNAPSHOT_LIMITS.bodyFieldLength) {
+      violations.push(
+        `${key}: ${value.length} characters exceeds the ${SNAPSHOT_LIMITS.bodyFieldLength}-character limit`
+      );
+    }
+  }
+  const lists = [
+    "constraints",
+    "questions",
+    "surfaceMarkers",
+    "artifacts"
+  ];
+  for (const key of lists) {
+    const items = i[key];
+    if (!Array.isArray(items)) continue;
+    if (items.length > SNAPSHOT_LIMITS.listLength) {
+      violations.push(
+        `${key}: ${items.length} entries exceeds the ${SNAPSHOT_LIMITS.listLength}-entry limit`
+      );
+    }
+    items.forEach((item, index) => {
+      if (typeof item === "string" && item.length > SNAPSHOT_LIMITS.listItemLength) {
+        violations.push(
+          `${key}[${index}]: ${item.length} characters exceeds the ${SNAPSHOT_LIMITS.listItemLength}-character limit`
+        );
+      }
+    });
+  }
+  return violations;
+}
 async function saveSnapshotFromIntent(cmd, cwd, laneFlag, scopeFlag, defaultScope, opts) {
   const lane = resolveLane(laneFlag, cwd);
   if (!lane) return false;
@@ -8510,7 +8545,96 @@ Fail-soft: failures exit 0 and never block; session-context refresh failures ren
   });
 }
 
+// src/commands/chat.ts
+function registerChat(program2) {
+  const chat = program2.command("chat").description("Send and read Slack / Discord channel messages").option("--surface <surface>", "slack | discord", "slack");
+  chat.addHelpText(
+    "after",
+    `
+Examples:
+  $ sechroom chat send C0123456789 "deploy is green" --surface slack
+  $ sechroom chat send 987654321098765432 "deploy is green" --surface discord --guild 123456789012345678
+  $ sechroom chat send C0123456789 "lgtm" --surface slack --as user --parent 1718049600.123456
+  $ sechroom chat messages --surface slack
+  $ sechroom chat replies 1718049600.123456 --surface slack
+  $ sechroom chat stop-tracking 1718049600.123456 --surface slack`
+  );
+  chat.command("send <channelId> <text>").description("Send a message to a channel (POST /chat/channel-messages/{surface})").option("--guild <guildId>", "Discord guild snowflake \u2014 required for --surface discord").option("--memory <memoryId>", "Attach a sechroom memory id").option("--no-track", "Don't capture replies to this message").option("--parent <parentMessage>", "Thread under a parent (Slack thread_ts / Discord message id)").option("--source <source>", "Source / lane stamp (renders an attribution footer; default: this checkout's pinned code-lane)").option("--as <as>", "Slack only: 'bot' (default) or 'user' (your linked Slack identity)", "bot").action(async (channelId, text2, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
+    const { surface, ...globals } = cmd.optsWithGlobals();
+    const json = Boolean(cmd.optsWithGlobals().json);
+    const cfg = resolveConfig(globals);
+    const data = await runApi("Sending message", async () => {
+      const client = await makeClient(cfg);
+      return client.POST("/chat/channel-messages/{surface}", {
+        params: { path: { surface: String(surface) } },
+        body: {
+          channelId,
+          text: text2,
+          guildId: opts.guild ?? null,
+          attachedMemoryId: opts.memory ?? null,
+          trackReplies: opts.track,
+          parentMessage: opts.parent ?? null,
+          source,
+          as: opts.as
+        }
+      });
+    });
+    if (!data.ok) {
+      if (json) {
+        emit(data, true);
+      } else {
+        process.stderr.write(
+          `${err("\u2717")} send failed: ${data.upstreamError ?? "error"}${data.errorDescription ? ` \u2014 ${data.errorDescription}` : ""}
+`
+        );
+      }
+      process.exit(1);
+    }
+    const idPart = data.persistedId ? ` ${style.dim(`(${data.persistedId})`)}` : "";
+    emitAction(`sent to ${surface} ${style.bold(channelId)}${idPart}`, data, json);
+  });
+  chat.command("messages").description("List recent channel messages (GET /chat/channel-messages/{surface})").action(async (_opts, cmd) => {
+    const { surface, ...globals } = cmd.optsWithGlobals();
+    const cfg = resolveConfig(globals);
+    const data = await runApi("Fetching messages", async () => {
+      const client = await makeClient(cfg);
+      return client.GET("/chat/channel-messages/{surface}", {
+        params: { path: { surface: String(surface) } }
+      });
+    });
+    emit(data, cmd.optsWithGlobals().json);
+  });
+  chat.command("replies <messageId>").description("List thread replies for a message (GET /chat/channel-messages/by-id/{id}/replies)").action(async (messageId, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await runApi("Fetching replies", async () => {
+      const client = await makeClient(cfg);
+      return client.GET("/chat/channel-messages/by-id/{id}/replies", {
+        params: { path: { id: messageId } }
+      });
+    });
+    emit(data, cmd.optsWithGlobals().json);
+  });
+  chat.command("stop-tracking <messageId>").description("Stop watching a message for replies (POST .../by-id/{id}/stop-tracking-replies)").action(async (messageId, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await runApi("Stopping reply tracking", async () => {
+      const client = await makeClient(cfg);
+      return client.POST("/chat/channel-messages/by-id/{id}/stop-tracking-replies", {
+        params: { path: { id: messageId } },
+        body: {}
+      });
+    });
+    emitAction(`stopped tracking replies on ${style.bold(messageId)}`, data, cmd.optsWithGlobals().json);
+  });
+}
+
 // src/commands/checkpoint.ts
+import { mkdirSync as mkdirSync15, writeFileSync as writeFileSync14 } from "fs";
+import { dirname as dirname14, join as join17 } from "path";
+var CHECKPOINT_UNCHANGED_EXIT_CODE = 3;
+function checkpointUnchangedLine(snapshotId) {
+  return `${style.bold("=")} unchanged ${style.dim(`(${snapshotId} already current)`)} \u2014 no new snapshot; the local file was left as-is`;
+}
 function registerCheckpoint(program2) {
   program2.command("checkpoint").description(
     "Checkpoint working state: create a continuity snapshot (server-validated) AND sync ./.sechroom/continuity.json in one step"
@@ -8558,6 +8682,13 @@ Examples:
         "no lane resolved \u2014 pass --lane, set SECHROOM_LANE, or pin one in ./.sechroom/lane.json (code-lane). See `sechroom lane`."
       );
     }
+    const overLimit = snapshotLimitViolations(merged);
+    if (overLimit.length > 0) {
+      fail(
+        `snapshot exceeds the field limits \u2014 trim and retry:
+  ${overLimit.join("\n  ")}`
+      );
+    }
     const scope = merged.scope ?? "session";
     const body = {
       laneId: lane,
@@ -8604,6 +8735,16 @@ Examples:
       const client = await makeClient(cfg);
       return client.POST("/continuity/snapshots", { body });
     });
+    const previousSnapshotId = base.lastSnapshotId;
+    if (previousSnapshotId && data.snapshotId === previousSnapshotId) {
+      process.exitCode = CHECKPOINT_UNCHANGED_EXIT_CODE;
+      if (json) {
+        emit({ snapshotId: data.snapshotId, lane, scope, unchanged: true, file: null }, true);
+        return;
+      }
+      process.stdout.write(checkpointUnchangedLine(data.snapshotId) + "\n");
+      return;
+    }
     const path = resolveIntentPath(cwd) ?? join17(cwd, INTENT_FILE);
     const fileBody = { ...merged, scope, lastSnapshotId: data.snapshotId };
     mkdirSync15(dirname14(path), { recursive: true });
@@ -8641,7 +8782,7 @@ function registerClose(program2) {
   ).option(
     "--to-version <n>",
     "Pin the Reference edge at this task version \u2014 the DISPATCHED version the executor worked against (D-continuity-2). Default: the task's current version (status flips are metadata edits that don't bump the version, so current == dispatched in the normal case; pass this when the task's content changed between dispatch and close)."
-  ).option("--source <source>", "Source / lane stamp", "cli").addHelpText(
+  ).option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").addHelpText(
     "after",
     `
 Examples:
@@ -8653,6 +8794,7 @@ Examples:
   $ sechroom close --task mem_XXXX --verdict pass --workspace wsp_ZZZZ \\
       --title "done" --file ./closeout.md`
   ).action(async (opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const json = cmd.optsWithGlobals().json;
     const verdict = String(opts.verdict);
@@ -8712,7 +8854,7 @@ Examples:
           type: "reference",
           content: "{}",
           confidence: 1,
-          source: opts.source,
+          source,
           archetype: "Document",
           title: opts.title,
           tags,
@@ -8769,7 +8911,7 @@ Examples:
           params: { path: { memoryId: opts.task } },
           body: {
             memoryId: opts.task,
-            source: opts.source,
+            source,
             tags: nextTags
           }
         })
@@ -10915,7 +11057,8 @@ Examples:
     "--owner-type <ownerType>",
     "Workspace | Project | Unfiled",
     "Unfiled"
-  ).option("--owner-id <ownerId>", "Owner id (required for Workspace/Project)").option("--source <source>", "Source / lane stamp", "cli").option("--confidence <n>", "Confidence 0..1", "1.0").action(async (opts, cmd) => {
+  ).option("--owner-id <ownerId>", "Owner id (required for Workspace/Project)").option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").option("--confidence <n>", "Confidence 0..1", "1.0").action(async (opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const { text: text2, defaultTitle } = resolveCreateBody(opts.text, opts.file);
     const title = opts.title ?? defaultTitle;
@@ -10928,7 +11071,7 @@ Examples:
           type: opts.type,
           content: "{}",
           confidence: Number(opts.confidence),
-          source: opts.source,
+          source,
           archetype: "Document",
           title: title ?? null,
           tags: opts.tag ?? null,
@@ -10957,7 +11100,8 @@ Examples:
     "--create-workspace",
     "Create the --workspace when its name matches nothing",
     false
-  ).option("--recursive", "Walk subdirectories of a given directory", false).option("--type <type>", "Memory type", "reference").option("--tag <tag...>", "Tags applied to every memory (repeatable)").option("--source <source>", "Source / lane stamp", "cli").option("--confidence <n>", "Confidence 0..1", "1.0").option("--dry-run", "Resolve and print the plan; write nothing", false).action(async (paths, opts, cmd) => {
+  ).option("--recursive", "Walk subdirectories of a given directory", false).option("--type <type>", "Memory type", "reference").option("--tag <tag...>", "Tags applied to every memory (repeatable)").option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").option("--confidence <n>", "Confidence 0..1", "1.0").option("--dry-run", "Resolve and print the plan; write nothing", false).action(async (paths, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const json = Boolean(cmd.optsWithGlobals().json);
     const dryRun = Boolean(opts.dryRun);
@@ -11070,7 +11214,7 @@ ${plan.rows.map(
           workspaceId: workspace.id,
           type: opts.type,
           tags: opts.tag ?? null,
-          source: opts.source,
+          source,
           confidence: Number(opts.confidence)
         },
         ports,
@@ -11192,7 +11336,8 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
     "--replace-all",
     "Replace every occurrence (default: first only)",
     false
-  ).option("--regenerate-filing", "Re-run filing after the edit", false).option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  ).option("--regenerate-filing", "Re-run filing after the edit", false).option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Editing memory text", async () => {
       const client = await makeClient(cfg);
@@ -11204,7 +11349,7 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
           newText: opts.new,
           replaceAll: Boolean(opts.replaceAll),
           regenerateFiling: Boolean(opts.regenerateFiling),
-          source: opts.source
+          source
         }
       });
     });
@@ -11216,7 +11361,8 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
   });
   memory.command("edit-text-batch <memoryId>").description(
     "Apply many find/replace edits (POST /memories/{memoryId}/edit-text-batch)"
-  ).requiredOption("--edit <old=>new...>", "Edit as 'old=>new' (repeatable)").option("--replace-all", "Apply replaceAll to every edit", false).option("--regenerate-filing", "Re-run filing after the edits", false).option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  ).requiredOption("--edit <old=>new...>", "Edit as 'old=>new' (repeatable)").option("--replace-all", "Apply replaceAll to every edit", false).option("--regenerate-filing", "Re-run filing after the edits", false).option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const replaceAll = Boolean(opts.replaceAll);
     const edits = opts.edit.map((spec) => {
@@ -11242,7 +11388,7 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
           memoryId,
           edits,
           regenerateFiling: Boolean(opts.regenerateFiling),
-          source: opts.source
+          source
         }
       });
     });
@@ -11267,7 +11413,8 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
     "--bump-version",
     "Bump the version chain (use for a content reinterpretation, e.g. a type promotion)",
     false
-  ).option("--source <source>", "Contributing lane stamp (attribution)", "cli").action(async (memoryId, opts, cmd) => {
+  ).option("--source <source>", "Contributing lane stamp (attribution; default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const json = cmd.optsWithGlobals().json;
     const hasTagOps = Boolean(opts.tag || opts.addTag || opts.removeTag);
@@ -11299,7 +11446,7 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
     }
     const body = {
       memoryId,
-      source: opts.source,
+      source,
       bumpVersion: Boolean(opts.bumpVersion)
     };
     if (opts.title !== void 0) body.title = opts.title;
@@ -11323,13 +11470,14 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
       json
     );
   });
-  memory.command("archive <memoryId>").description("Archive a memory (POST /memories/{memoryId}/archive)").option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  memory.command("archive <memoryId>").description("Archive a memory (POST /memories/{memoryId}/archive)").option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Archiving memory", async () => {
       const client = await makeClient(cfg);
       return client.POST("/memories/{memoryId}/archive", {
         params: { path: { memoryId } },
-        body: { source: opts.source }
+        body: { source }
       });
     });
     emitAction(
@@ -11340,13 +11488,14 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
   });
   memory.command("restore <memoryId>").description(
     "Restore an archived memory (POST /memories/{memoryId}/restore)"
-  ).option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  ).option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Restoring memory", async () => {
       const client = await makeClient(cfg);
       return client.POST("/memories/{memoryId}/restore", {
         params: { path: { memoryId } },
-        body: { source: opts.source }
+        body: { source }
       });
     });
     emitAction(
@@ -11360,7 +11509,8 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
   ).requiredOption(
     "--owner-type <ownerType>",
     "Unfiled | Workspace | Project | Candidate"
-  ).option("--owner-id <ownerId>", "Owner id (required unless Unfiled)").option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  ).option("--owner-id <ownerId>", "Owner id (required unless Unfiled)").option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Moving memory", async () => {
       const client = await makeClient(cfg);
@@ -11371,7 +11521,7 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
             type: opts.ownerType,
             id: String(opts.ownerId ?? "")
           },
-          source: opts.source
+          source
         }
       });
     });
@@ -11423,7 +11573,8 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
   ).requiredOption(
     "--content <content>",
     "Reverted content JSON (the target version's content)"
-  ).option("--source <source>", "Source / lane stamp", "cli").action(async (memoryId, opts, cmd) => {
+  ).option("--source <source>", "Source / lane stamp (default: this checkout's pinned code-lane)").action(async (memoryId, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Reverting memory", async () => {
       const client = await makeClient(cfg);
@@ -11433,7 +11584,7 @@ Note: CLI memory get omits relationships by default; MCP get_memory includes the
           fromVersion: Number(opts.fromVersion),
           revertedContent: opts.content,
           revertedText: opts.text,
-          source: opts.source
+          source
         }
       });
     });
@@ -12473,7 +12624,8 @@ version, the shared template stays clean, and you can discard back anytime.
       make = await promptYesNo("Make a personal copy to customise?");
     }
     if (make) {
-      await createOverride(cfg, resolved, personalWorkspaceId);
+      const source = resolveSourceLane(void 0);
+      await createOverride(cfg, resolved, personalWorkspaceId, source);
       process.stderr.write(
         `\u2713 personal copy created for ${instr.surfaceKey} \u2014 edit it on the Agent setup page or via the API.
 `
@@ -12837,7 +12989,10 @@ function registerSetup(program2, deps = {}) {
   ).option(
     "--body <markdown>",
     "section body (default: a TODO scaffold to edit later)"
-  ).option("--no-regen", "skip the agent-files regen after authoring").option("--dry-run", "print what would be authored; write nothing", false).addHelpText(
+  ).option("--no-regen", "skip the agent-files regen after authoring").option(
+    "--source <source>",
+    "Source / lane stamp (default: this checkout's pinned code-lane)"
+  ).option("--dry-run", "print what would be authored; write nothing", false).addHelpText(
     "after",
     `
 The memo carries the two conventions a workspace-conventions section needs (FR-sechroom-236):
@@ -12850,6 +13005,7 @@ Examples:
   $ sechroom setup new-convention "Backend testing" --kind standard --body "- run dotnet test ..."
   $ sechroom setup new-convention "Draft section" --no-regen   author only, regen later`
   ).action(async (titleParts, opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const json = Boolean(cmd.optsWithGlobals().json);
     const title = titleParts.join(" ").trim();
@@ -12885,7 +13041,7 @@ Examples:
           type: draft.kind,
           content: "{}",
           confidence: 1,
-          source: "cli-new-convention",
+          source,
           archetype: "Document",
           title: draft.title,
           tags: draft.tags,
@@ -13463,11 +13619,20 @@ async function ensureTenant(baseUrl, g, opts) {
     clientId: persisted.clientId
   };
 }
-async function ensureAuth(cfg, yes) {
-  if (process.env.SECHROOM_TOKEN) return;
+function hasUsableCredential() {
+  if (process.env.SECHROOM_TOKEN) return true;
   const cached = readToken();
-  const usable = Boolean(cached?.accessToken) && (cached.expiresAt === void 0 || Date.now() < cached.expiresAt - 6e4 || Boolean(cached.refreshToken));
-  if (usable) return;
+  return Boolean(cached?.accessToken) && (cached.expiresAt === void 0 || Date.now() < cached.expiresAt - 6e4 || Boolean(cached.refreshToken));
+}
+function requireCredentialForPreview(preview, dryRun) {
+  if (!preview || hasUsableCredential()) return;
+  const flag = dryRun ? "--dry-run" : "--check";
+  fail(
+    `sechroom onboard ${flag} needs an existing sign-in; run \`sechroom login\` first, then re-run the preview.`
+  );
+}
+async function ensureAuth(cfg, yes) {
+  if (hasUsableCredential()) return;
   if (!canPrompt() || yes) {
     fail(
       "Not signed in. Run `sechroom login` first, or set SECHROOM_TOKEN for headless use."
@@ -13806,6 +13971,7 @@ Examples:
     if (opts.designLane) process.env.SECHROOM_DESIGN_LANE = opts.designLane;
     if (opts.recurse) {
       const baseUrl2 = resolveBaseUrl(g);
+      requireCredentialForPreview(dryRun || check, dryRun);
       await ensureAuth(
         {
           baseUrl: baseUrl2,
@@ -13830,6 +13996,7 @@ Examples:
       return;
     }
     const baseUrl = resolveBaseUrl(g);
+    requireCredentialForPreview(dryRun || check, dryRun);
     await ensureAuth(
       {
         baseUrl,
@@ -13846,7 +14013,12 @@ Examples:
       local: Boolean(opts.local) || scope === "project",
       here: scope === "project" ? true : Boolean(opts.here),
       workspace: opts.workspace,
-      persist: !check
+      // Both previews are read-only. `--dry-run` promises to "walk through without
+      // writing files or changing the profile", but only `--check` was in this
+      // guard, so a dry run could still create or rewrite `.sechroom.json` /
+      // `~/.config/sechroom/config.json` before the operator approved anything
+      // (FR-sechroom-710). Matches how `ensureTimezone` is already gated below.
+      persist: !(dryRun || check)
     });
     const tz = await ensureTimezone(cfg, { yes, dryRun: dryRun || check });
     if (!json && tz.action !== "already-set") {
@@ -14877,14 +15049,15 @@ Examples:
   $ sechroom worklog append --text "shipped CLI help + onboarding scope; PR #1430"
   $ sechroom worklog append --text "smoke passed" --source claude-code-chris --title "CLI smoke"`
   );
-  worklog.command("append").description("Append a work-log entry (POST /operator-surface/work-log/append)").requiredOption("--text <text>", "Entry body (short bullets / pointers) \u2014 the bullet").option("--source <source>", "Lane stamp (e.g. claude-code-chris) \u2014 laneId", "cli").option("--workspace <workspaceId>", "Target work-log workspace (default: caller's daily log)").option("--title <title>", "Optional entry title").action(async (opts, cmd) => {
+  worklog.command("append").description("Append a work-log entry (POST /operator-surface/work-log/append)").requiredOption("--text <text>", "Entry body (short bullets / pointers) \u2014 the bullet").option("--source <source>", "Lane stamp (e.g. claude-code-chris) \u2014 laneId (default: this checkout's pinned code-lane)").option("--workspace <workspaceId>", "Target work-log workspace (default: caller's daily log)").option("--title <title>", "Optional entry title").action(async (opts, cmd) => {
+    const source = resolveSourceLane(opts.source);
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Appending work-log entry", async () => {
       const client = await makeClient(cfg);
       return client.POST("/operator-surface/work-log/append", {
         body: {
           bullet: opts.text,
-          laneId: opts.source ?? null,
+          laneId: source,
           workspaceId: opts.workspace ?? null,
           title: opts.title ?? null
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sechroom/cli",
-  "version": "2026.9.1",
+  "version": "2026.9.2",
   "description": "Command-line interface for Sechroom — sign in, wire your AI tools, and work with your sechroom from the terminal.",
   "type": "module",
   "license": "UNLICENSED",