session-orchestrator 5.0.0 → 5.2.0

package/pi/prompts/dispatcher.md

@@ -1,12 +1,12 @@
 ---
-description: Pick the next-best repo to work on across the portfolio — rank free repos, recommend one, claim its lease atomically, and route to the entry command
+description: "Use when you want the orchestrator to pick the next repo to work on across your whole portfolio — it enumerates candidate repos below the confinement root, resolves free/busy from each repo's session.lock lease, ranks the FREE ones by backlog priority × staleness × readiness, recommends the single most worthwhile one via AskUserQuestion, atomically claims it, and routes you to the chosen entry command. Triggers: \"what should I work on next\", \"dispatch me to a repo\", \"pick the next project\", \"run /dispatcher\". <example>Context: operator finished a session and wants the next-best repo across the portfolio. user: \"/dispatcher\" assistant: \"Ranked 18 free repos — top recommendation: Pencil-Designs (score 4.50, 90d stale). Confirm via the picker, I'll claim its lease atomically, then route you to /session deep.\"</example>"
 argument-hint: "[--dry-run] [--repo <name>]"
 ---
 
 # /dispatcher
 
-Use the Session Orchestrator command definition at `commands/dispatcher.md`.
+Use the Session Orchestrator skill definition at `skills/dispatcher/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/eli5.md

@@ -1,12 +1,12 @@
 ---
-description: Say the last answer again in plain words — same facts, in the order the operator needs them. Optional topic argument.
+description: "Explain a topic like I'm a 5 year old — restate my last output, or a named topic, in plain words without dropping a single fact. Use when the user types /eli5 [topic], or says an answer was too technical, too long, or unclear about what he now has to do."
 argument-hint: "[topic]"
 ---
 
 # /eli5
 
-Use the Session Orchestrator command definition at `commands/eli5.md`.
+Use the Session Orchestrator skill definition at `skills/eli5/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/eval.md

@@ -1,12 +1,12 @@
 ---
-description: Run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed session against the pre-registered rubric-v1 dimensions
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v1 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 
 # /eval
 
-Use the Session Orchestrator command definition at `commands/eval.md`.
+Use the Session Orchestrator skill definition at `skills/eval/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/evolve.md

@@ -1,12 +1,12 @@
 ---
-description: Extract session patterns into reusable learnings
+description: "Use this skill when extracting session patterns into reusable learnings. Three modes: analyze (extract from session history), review (edit/manage existing learnings), list (display active learnings). Manages .orchestrator/metrics/learnings.jsonl."
 argument-hint: "[analyze|review|list|dialectic [--apply]]"
 ---
 
 # /evolve
 
-Use the Session Orchestrator command definition at `commands/evolve.md`.
+Use the Session Orchestrator skill definition at `skills/evolve/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/go.md

@@ -5,8 +5,8 @@ argument-hint: "[optional instructions]"
 
 # /go
 
-Use the Session Orchestrator command definition at `commands/go.md`.
+Use the Session Orchestrator skill definition at `skills/go/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/grill.md

@@ -1,12 +1,12 @@
 ---
-description: Stress-test a plan, design, or PRD before any build — relentless one-question-at-a-time interrogation that hunts contradictions against the code and challenges assumptions. Composable; no HARD-GATE.
+description: "Use when the user wants a plan, design, or PRD stress-tested before any build — relentlessly interrogates one decision at a time, grounds every question in the codebase, hunts contradictions against the domain language and the code, and challenges the load-bearing assumptions. Triggered by \"grill me\", \"stress-test this plan\", \"poke holes in my design\". Composable — run standalone or as an adversarial pass before /plan feature."
 argument-hint: "[file-path-or-topic]"
 ---
 
 # /grill
 
-Use the Session Orchestrator command definition at `commands/grill.md`.
+Use the Session Orchestrator skill definition at `skills/grill/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/harness-audit.md

@@ -1,12 +1,11 @@
 ---
 description: Run the harness audit and report the rubric score for this repository
-argument-hint: ""
 ---
 
 # /harness-audit
 
-Use the Session Orchestrator command definition at `commands/harness-audit.md`.
+Use the Session Orchestrator skill definition at `skills/harness-audit/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/memory-cleanup.md

@@ -1,12 +1,12 @@
 ---
-description: Manual memory consolidation — review, consolidate, and prune memory files (Dream-equivalent)
+description: "Use this skill when performing manual memory consolidation (Dream-equivalent). Reviews, consolidates, and prunes memory files under ~/.claude/projects/*/memory/. Run after major refactors, every 5+ sessions, or when memory quality degrades (broken links, stale references, contradictions, MEMORY.md > 200 lines). Invoke with /memory-cleanup."
 argument-hint: "[--dry-run | --apply-pending]"
 ---
 
 # /memory-cleanup
 
-Use the Session Orchestrator command definition at `commands/memory-cleanup.md`.
+Use the Session Orchestrator skill definition at `skills/memory-cleanup/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/npm-publish.md

@@ -0,0 +1,11 @@
+---
+description: "Use when publishing this package to npm — a version release (npm publish), verifying the registry/pi.dev listing, or diagnosing npm auth failures (E403 2FA/token errors). Token-based flow via NPM_TOKEN in .env.local with a temp userconfig, the leakage gate before every publish, post-publish verification and marker/badge upkeep. Trigger on \"publish to npm\", \"npm release\", \"E403 publish error\"."
+---
+
+# /npm-publish
+
+Use the Session Orchestrator skill definition at `skills/npm-publish/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/persona-panel.md

@@ -1,12 +1,12 @@
 ---
-description: Run a parallel multi-persona domain-expert review panel against a file, directory, or output range
+description: "Use this skill when you need multi-persona parallel content review — domain experts, buyer personas, compliance reviewers, or custom catalog entries reviewing a target file or output. Dispatches N persona agents in parallel, consolidates verdicts via a configurable mode (voting-quorum, hard-gate-threshold, or coordinator-summary), and writes a timestamped sidecar to .orchestrator/persona-panel/. Invoked via /persona-panel <target-path>."
 argument-hint: "<target> [--personas <names,...>] [--mode <voting|hard-gate|summary>] [--threshold <M-of-N|all|any>] [--grounding <off|re-derive>] [--dry-run]"
 ---
 
 # /persona-panel
 
-Use the Session Orchestrator command definition at `commands/persona-panel.md`.
+Use the Session Orchestrator skill definition at `skills/persona-panel/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/plan.md

@@ -1,12 +1,12 @@
 ---
-description: Plan a new project, feature, or retrospective with structured requirement gathering
+description: "Use this skill when performing structured project planning and PRD generation with three modes: new (project kickoff with repo scaffolding), feature (compact feature PRD), retro (data-driven retrospective). All modes share a researched Q&A engine that dispatches parallel Explore agents before each question wave, presents options via AskUserQuestion with recommendations, and produces documents with prioritized issue creation."
 argument-hint: "[new|feature|retro]"
 ---
 
 # /plan
 
-Use the Session Orchestrator command definition at `commands/plan.md`.
+Use the Session Orchestrator skill definition at `skills/plan/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/portfolio.md

@@ -5,8 +5,8 @@ argument-hint: "[--dry-run] [--repo <name>]"
 
 # /portfolio
 
-Use the Session Orchestrator command definition at `commands/portfolio.md`.
+Use the Session Orchestrator skill definition at `skills/portfolio/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/reconcile.md

@@ -1,12 +1,12 @@
 ---
-description: Reconcile learnings into .claude/rules/ proposals — on-demand version of session-end Phase 3.6.8
+description: Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
 argument-hint: "[--dry-run]"
 ---
 
 # /reconcile
 
-Use the Session Orchestrator command definition at `commands/reconcile.md`.
+Use the Session Orchestrator skill definition at `skills/reconcile/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/release.md

@@ -1,12 +1,12 @@
 ---
-description: Cut a release — the order the steps must run in, and the criteria that abort a release
+description: "Cut a release — the order the steps must run in, and the criteria that abort a release"
 argument-hint: "[X.Y.Z]"
 ---
 
 # /release
 
-Use the Session Orchestrator command definition at `commands/release.md`.
+Use the Session Orchestrator skill definition at `skills/release/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/repo-audit.md

@@ -1,12 +1,11 @@
 ---
-description: Run a 9-category baseline compliance audit on the current repository
-argument-hint: ""
+description: "Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: \"/repo-audit\" assistant: \"Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar.\" <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9 categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>"
 ---
 
 # /repo-audit
 
-Use the Session Orchestrator command definition at `commands/repo-audit.md`.
+Use the Session Orchestrator skill definition at `skills/repo-audit/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/session.md

@@ -1,5 +1,5 @@
 ---
-description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+description: "Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)"
 argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 

package/pi/prompts/spinout.md

@@ -1,12 +1,12 @@
 ---
-description: Guided 5-step venture-spinout / sanitized-fork runbook (copy + fresh-init + SNAPSHOT-FREEZE) — interactive, not scripted
+description: "Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'."
 argument-hint: "[--type venture|snapshot] [--dry-run]"
 ---
 
 # /spinout
 
-Use the Session Orchestrator command definition at `commands/spinout.md`.
+Use the Session Orchestrator skill definition at `skills/spinout/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/sunset-review.md

@@ -1,12 +1,12 @@
 ---
-description: Identify unused / near-zero-use / stale skills, agents, and commands as Demote or Retire candidates (read-only; never deletes)
+description: "Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: \"/sunset-review\" assistant: \"Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision.\" <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>"
 argument-hint: "[--kind skill|agent|command] [--window-days N]"
 ---
 
 # /sunset-review
 
-Use the Session Orchestrator command definition at `commands/sunset-review.md`.
+Use the Session Orchestrator skill definition at `skills/sunset-review/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/templates-ack.md

@@ -1,5 +1,5 @@
 ---
-description: Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session
+description: "Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session"
 argument-hint: "[optional-reason]"
 ---
 

package/pi/prompts/test.md

@@ -1,12 +1,12 @@
 ---
-description: Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues
+description: "Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues"
 argument-hint: "[scope|profile-name] [--since <git-ref>] [--full]"
 ---
 
 # /test
 
-Use the Session Orchestrator command definition at `commands/test.md`.
+Use the Session Orchestrator skill definition at `skills/test/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/ux-grill.md

@@ -1,12 +1,12 @@
 ---
-description: Grill a running web app's UX — a deterministic mechanical pass (axe, target size, overflow, journeys) followed by a screenshot-grounded interrogation of the operator.
+description: "Use when a running web app's UX has to be audited reproducibly rather than by feel — a deterministic mechanical pass over routes and viewports (axe, target size, horizontal overflow, page title, scripted journeys) followed by a screenshot-grounded interrogation of the operator, journey by journey, with two persona lenses from the target repo's manifest. Triggered by \"grill the UX\", \"roast the dashboard\", \"UX-Audit\", \"/ux-grill\". Bootstraps its own manifest from a loopback URL on the first run, so it never requires a hand-written file to start."
 argument-hint: "[url | manifest-path]"
 ---
 
 # /ux-grill
 
-Use the Session Orchestrator command definition at `commands/ux-grill.md`.
+Use the Session Orchestrator skill definition at `skills/ux-grill/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/scripts/archive-closed-prds.mjs

@@ -41,7 +41,6 @@
 
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 
 import { findProjectRoot, resolveInstructionFile, warn } from './lib/common.mjs';
@@ -52,6 +51,7 @@ import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
 import { readLock } from './lib/session-lock.mjs';
 import { resolveStateMdPath } from './lib/state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './lib/state-md/yaml-parser.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_PRD_DIR = 'docs/prd';
 const DEFAULT_VAULT_SUBDIR = '01-projects/session-orchestrator/prd';
@@ -635,7 +635,7 @@ export function main({
 // CLI guard — prevents process.exit during test-time imports
 // ---------------------------------------------------------------------------
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   try {
     const { code } = main();
     process.exit(code ?? 0);

package/scripts/auq-audit.mjs

@@ -76,6 +76,7 @@ import {
 } from './lib/auq/schema.mjs';
 import { corpusKindOf, parseRepo } from './lib/auq/parse.mjs';
 import { writeStdoutLineSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT_DEFAULT = path.resolve(HERE, '..');
@@ -818,8 +819,6 @@ function pkgVersion() {
   }
 }
 
-const invokedDirectly =
-  process.argv[1] !== undefined &&
-  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) main();

package/scripts/backfill-abandoned-sessions.mjs

@@ -39,11 +39,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { isLockLive, readLock } from './lib/session-lock.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
@@ -101,6 +103,24 @@ function readJsonl(filePath) {
  * session.started UUID, each bridged to its semantic id via lock.acquired
  * where one exists. Preserves first-seen order.
  *
+ * THIS VERY PROCESS is excluded (#1376). The shared core's own
+ * `skipped-own-live-lock` branch used to carry that job alone, but it is now
+ * defeasible: `ownSessionIsEnding` lets the SessionEnd hook record its own
+ * session, so the CLI must not depend on a branch whose meaning the caller
+ * chooses. The exclusion needs THREE conjuncts, and dropping any one of them
+ * breaks it in a different direction:
+ *   1. the candidate names the lock (by either id, including the #863 (d)
+ *      lock shape that stores the semantic id in `session_id`),
+ *   2. the lock is LIVE — a stale lock names a session nobody is running, and
+ *      reconstructing it is exactly this CLI's job, and
+ *   3. a PROCESS-LOCAL id (hook payload / harness env, never the repo-global
+ *      lock — see `readProcessLocalSessionIds`) matches the lock, which is
+ *      what distinguishes THIS process from a PEER's running session in the
+ *      same working copy. Without it the repo-global lock would vouch for
+ *      itself and a peer's live session would read as "me".
+ * A peer's live session is NOT excluded here and does not need to be: the core
+ * still rejects it through the untouched own/foreign live-lock guards.
+ *
  * @param {{ repoRoot: string }} args
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
@@ -124,17 +144,51 @@ export function planSessions({ repoRoot }) {
   }
   const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
+  const runningIds = readRunningSessionIds(repoRoot);
+
   const seen = new Set();
   const plan = [];
   for (const ev of events) {
     if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') continue;
     if (seen.has(ev.session_id)) continue;
     seen.add(ev.session_id);
-    plan.push({ sessionId: ev.session_id, semanticSessionId: semanticByUuid.get(ev.session_id) ?? null });
+    const semanticSessionId = semanticByUuid.get(ev.session_id) ?? null;
+    if (runningIds.has(ev.session_id)
+      || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
+    plan.push({ sessionId: ev.session_id, semanticSessionId });
   }
   return plan;
 }
 
+/**
+ * The id(s) naming the session THIS process is, when that session holds the
+ * live lock — else the empty set (#1376). Never throws: an unreadable lock,
+ * an absent one, or an env without any process-local id all degrade to "no
+ * exclusion", which is the pre-#1376 behaviour.
+ *
+ * @param {string} repoRoot
+ * @returns {Set<string>}
+ */
+function readRunningSessionIds(repoRoot) {
+  const ids = new Set();
+  try {
+    const lock = readLock({ repoRoot });
+    if (!lock || !isLockLive(lock)) return ids;
+    const lockIds = [lock.session_id, lock.semantic_session_id]
+      .filter((id) => typeof id === 'string' && id.length > 0);
+    const processLocal = new Set(readProcessLocalSessionIds());
+    // Conjunct 3 — only a PROCESS-LOCAL witness may promote the repo-global
+    // lock to "this is me". Membership is tested against the lock's ids, not
+    // the other way round, so an env var that happens to name some other
+    // session never widens the exclusion.
+    if (!lockIds.some((id) => processLocal.has(id))) return ids;
+    for (const id of lockIds) ids.add(id);
+  } catch {
+    /* readLock is no-throw by contract; the contract is not ours to trust */
+  }
+  return ids;
+}
+
 /**
  * Cheap pre-filter (#926): the set of session ids ALREADY present in
  * sessions.jsonl.
@@ -527,7 +581,7 @@ async function main() {
   process.exit(0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun = isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`backfill-abandoned-sessions: unexpected error: ${err?.stack ?? err}\n`);

package/scripts/backfill-evidence-digest.mjs

@@ -50,6 +50,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 
 import { computeEvidenceDigest } from './lib/reconcile/renderer.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 /** ISO-8601 instant — mirrors the renderer's `EVIDENCE_RECORDED_AT_RE`. */
 const EVIDENCE_RECORDED_AT_RE = /^\d{4}-\d{2}-\d{2}T[0-9:.]+(?:Z|[+-]\d{2}:\d{2})$/;
@@ -373,4 +374,4 @@ function main(argv) {
   process.exit(unsealable === 0 ? 0 : 1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));
+if (isMainModule(import.meta.url)) main(process.argv.slice(2));

package/scripts/backfill-learnings-from-vault.mjs

@@ -64,7 +64,6 @@
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, basename, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
@@ -72,6 +71,7 @@ import { subjectToSlug, parseFrontmatter } from './lib/vault-mirror/utils.mjs';
 import { kebab } from './lib/learnings/kebab.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { appendLearning, isBackupOf } from './lib/learnings/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
 const DEFAULT_STORE = '.orchestrator/metrics/learnings.jsonl';
@@ -962,7 +962,7 @@ export async function main(argv = [], deps = {}) {
 }
 
 /* c8 ignore start — CLI entrypoint */
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then(({ code }) => process.exit(code))
     .catch((err) => {

package/scripts/check-package-manager.mjs

@@ -67,6 +67,7 @@ import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const SELF_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -388,8 +389,7 @@ function parseArgs(argv) {
 }
 
 // CLI entry — only when run directly, not when imported (e.g. by tests).
-const isMain =
-  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   const { opts, unknown } = parseArgs(process.argv.slice(2));

package/scripts/ci/assert-vitest-green.mjs

@@ -50,6 +50,7 @@
 //   the existing bare message and the exit-code contract is unchanged.
 
 import { readFileSync } from 'node:fs';
+import { isMainModule } from '../lib/is-main-module.mjs';
 
 const DEFAULT_MIN_TESTS = 5000;
 
@@ -232,7 +233,7 @@ function parseArgs(argv) {
 }
 
 // CLI entry — only when run directly, not when imported by tests.
-const isMain = import.meta.url === `file://${process.argv[1]}`;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const { path, minTests, logPath } = parseArgs(process.argv.slice(2));
   if (!path) {

package/scripts/emit-session.mjs

@@ -26,7 +26,6 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { appendJsonl } from './lib/common.mjs';
 import {
   MEMORY_CLEANUP_EVENT,
@@ -42,6 +41,7 @@ import {
   clampTimestampsMonotonic,
   aliasLegacyEndedAt,
 } from './lib/session-schema.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 export { serializeSessionLineChecked };
 
@@ -277,8 +277,7 @@ async function main() {
 // not when imported as a module (e.g. by tests that exercise the exported
 // serializeSessionLineChecked seam — #662). Without this guard, importing the
 // module would block on stdin / exit the test process.
-const _isDirectRun =
-  process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const _isDirectRun =isMainModule(import.meta.url);
 
 if (_isDirectRun) {
   main().catch((err) => {

package/scripts/export-hw-learnings.mjs

@@ -63,6 +63,7 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.mjs';
 import { emitEvent, sessionAttribution } from './lib/events.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // Vault-relative default write target (Epic #774 — docs Public-Split removed
 // the prior in-repo generated telemetry doc in favor of the private Meta-Vault).
@@ -724,7 +725,7 @@ export async function exportHwLearnings(opts) {
 }
 
 // Run as CLI when invoked directly
-const isMain = import.meta.url === `file://${process.argv[1]}`;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const opts = parseArgs(process.argv.slice(2));
 

package/scripts/express-path.mjs

@@ -281,7 +281,7 @@ async function main() {
 
   // The banner the coordinator echoes into the transcript — `/go` and
   // session-plan's Express Path Short-Circuit both key off this EXACT line
-  // (`commands/go.md` § Express Path Detection), so it is written verbatim,
+  // (`skills/go/SKILL.md` § Express Path Detection), so it is written verbatim,
   // without the `express-path:` diagnostic prefix. Still stderr: stdout belongs
   // to the verdict.
   if (verdict.activated) {