pi-odd-worktree 0.0.0-stage → 1.0.0

package/lib/open-external.js

@@ -0,0 +1,106 @@
+'use strict';
+// External opener (key-consistency K3/S5): `o` in the odd viewer opens the
+// focused document through `$VISUAL`/`$EDITOR`.
+//
+// Fixed argv, no shell, injectable spawn, honest result: the promise never
+// rejects — a missing editor or a failed spawn resolves
+// `{ ok: false, error }` naming what is wrong, so the caller shows it
+// instead of failing silently. Success resolves `{ ok: true, editor }`.
+
+const OPEN_TIMEOUT_MS = 15000;
+
+function resolveEditor(opts = {}) {
+  if (typeof opts.editor === 'string' && opts.editor.trim() !== '') return opts.editor.trim();
+  let env = null;
+  try {
+    env = opts.env || process.env;
+  } catch {
+    env = null;
+  }
+  for (const name of ['VISUAL', 'EDITOR']) {
+    let value = null;
+    try {
+      value = env ? env[name] : null;
+    } catch {
+      value = null;
+    }
+    if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  }
+  return null;
+}
+
+function splitCommand(command) {
+  return String(command).trim().split(/\s+/).filter((part) => part.length > 0);
+}
+
+function shortError(err) {
+  if (err === null || err === undefined) return 'unknown error';
+  if (typeof err === 'string') return err.split('\n')[0];
+  return String((err && err.message) || err).split('\n')[0];
+}
+
+async function openExternal(target, opts = {}) {
+  if (typeof target !== 'string' || target.trim() === '') {
+    return { ok: false, error: 'nothing to open: no document is focused' };
+  }
+  const editor = resolveEditor(opts);
+  if (!editor) {
+    return { ok: false, error: 'no editor configured: set $VISUAL or $EDITOR to open documents outside Pi' };
+  }
+  const parts = splitCommand(editor);
+  const bin = parts[0];
+  const prefix = parts.slice(1);
+  let spawnImpl = opts.spawnImpl;
+  if (typeof spawnImpl !== 'function') {
+    try {
+      spawnImpl = require('node:child_process').spawn;
+    } catch (err) {
+      return { ok: false, error: `cannot open ${target}: child_process is unavailable` };
+    }
+  }
+  let child = null;
+  try {
+    // Fixed argv: the editor binary plus its own flags plus the target as
+    // one element. Never a shell string, so no quoting or injection.
+    child = spawnImpl(bin, [...prefix, target], { stdio: 'inherit', windowsHide: true });
+  } catch (err) {
+    return { ok: false, error: `cannot open ${target} with ${bin}: ${shortError(err)}` };
+  }
+  if (!child || typeof child.on !== 'function' || typeof child.once !== 'function') {
+    return { ok: false, error: `cannot open ${target} with ${bin}: the editor did not start` };
+  }
+  // A detached editor must not hold the session open waiting on it.
+  try {
+    if (typeof child.unref === 'function') child.unref();
+  } catch {
+    // Best effort only; the result below still reports honestly.
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      try {
+        clearTimeout(timer);
+      } catch {
+        // A dead timer never blocks the result.
+      }
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      finish({ ok: false, error: `cannot open ${target} with ${bin}: the editor did not start` });
+    }, OPEN_TIMEOUT_MS);
+    try {
+      child.once('error', (err) => {
+        finish({ ok: false, error: `cannot open ${target} with ${bin}: ${shortError(err)}` });
+      });
+      child.once('spawn', () => {
+        finish({ ok: true, editor: bin });
+      });
+    } catch (err) {
+      finish({ ok: false, error: `cannot open ${target} with ${bin}: ${shortError(err)}` });
+    }
+  });
+}
+
+module.exports = { openExternal, resolveEditor };

package/lib/preview-scroll-keys.js

@@ -0,0 +1,192 @@
+'use strict';
+// S1: ONE decision for the preview scroll bindings the full-screen readers
+// share, and ONE honest guard about the byte the terminal actually sends.
+//
+// The default pair is ctrl+j/k — the user asked for it to be printed whatever
+// the terminal reports — and the legend names it in both readers. ctrl+shift+j/k
+// and the printable Shift+J/K stay working alternatives for a host that only
+// negotiates the extended keyboard protocol or only delivers printable keys;
+// their hints leave the row so the footer does not list every alias.
+//
+// The one thing that must never move is Enter: a legacy terminal sends the same
+// LF byte for ctrl+j and Enter, so a bare newline is Enter and is refused before
+// any host matcher or decoder can claim it as a scroll key.
+//
+// Everything here is pure: the host's TUI helpers are injected, no module
+// state exists, and a hostile or partial host degrades to the bounded raw
+// table below rather than throwing inside a key handler.
+
+const ACTIONS = Object.freeze({
+  PAGE_DOWN: 'page-down',
+  PAGE_UP: 'page-up',
+  HALF_DOWN: 'half-down',
+  HALF_UP: 'half-up',
+});
+
+// The default pair, then the shifted alternate. Hosts spell the modifier order
+// both ways (`ctrl+shift+j` and `shift+ctrl+j`), so the shifted entry carries
+// both names; no rule ever matches a bare `j`/`k`, which move the list
+// selection.
+const RULES = [
+  { action: ACTIONS.PAGE_DOWN, names: ['ctrl+j'] },
+  { action: ACTIONS.PAGE_UP, names: ['ctrl+k'] },
+  // An extended-protocol terminal distinguishes ctrl+j/k from Enter and also
+  // reports the shifted pair; either one pages.
+  { action: ACTIONS.PAGE_DOWN, names: ['ctrl+shift+j', 'shift+ctrl+j'] },
+  { action: ACTIONS.PAGE_UP, names: ['ctrl+shift+k', 'shift+ctrl+k'] },
+  { action: ACTIONS.PAGE_DOWN, names: ['pagedown', 'pageDown'] },
+  { action: ACTIONS.PAGE_UP, names: ['pageup', 'pageUp'] },
+  // The printable Shift+J/K fallback: the same full-page action, so a legacy
+  // terminal keeps a working way to page the preview.
+  { action: ACTIONS.PAGE_DOWN, names: ['shift+j', 'J'] },
+  { action: ACTIONS.PAGE_UP, names: ['shift+k', 'K'] },
+  // The distinct Vim pair stays a HALF page and never stands in for the
+  // primary binding.
+  { action: ACTIONS.HALF_DOWN, names: ['ctrl+d'] },
+  { action: ACTIONS.HALF_UP, names: ['ctrl+u'] },
+];
+
+// Bare LF/CR mean Enter on a legacy terminal — and that terminal reports the
+// same byte as ctrl+j — so neither may page. VT is the legacy ctrl+k byte,
+// which those terminals cannot tell apart from a control character either.
+// This guard runs BEFORE the host matcher, so no matcher can claim a bare
+// newline and Enter keeps its confirm/comment meaning.
+const FORBIDDEN_RAW = new Set(['\n', '\r', '\x0b']);
+
+// Bounded fallback for exactly these keys, for hosts that inject no helpers or
+// an incomplete one. Modifiers other than the ones listed here never resolve.
+const RAW_ACTIONS = new Map([
+  ['\x1b[6~', ACTIONS.PAGE_DOWN],
+  ['\x1b[5~', ACTIONS.PAGE_UP],
+  ['\x04', ACTIONS.HALF_DOWN],
+  ['\x15', ACTIONS.HALF_UP],
+  ['J', ACTIONS.PAGE_DOWN],
+  ['K', ACTIONS.PAGE_UP],
+  ['\x1b[27;6;106~', ACTIONS.PAGE_DOWN],
+  ['\x1b[27;6;107~', ACTIONS.PAGE_UP],
+]);
+// Extended sequences carrying a press or repeat suffix: CSI-u (modifier 5 is
+// ctrl, 6 is shift+ctrl), the extended page keys, and ctrl+d/ctrl+u.
+const RAW_PATTERNS = [
+  { pattern: /^\x1b\[106;5(?::[12])?u$/, action: ACTIONS.PAGE_DOWN },
+  { pattern: /^\x1b\[107;5(?::[12])?u$/, action: ACTIONS.PAGE_UP },
+  { pattern: /^\x1b\[106;6(?::[12])?u$/, action: ACTIONS.PAGE_DOWN },
+  { pattern: /^\x1b\[107;6(?::[12])?u$/, action: ACTIONS.PAGE_UP },
+  { pattern: /^\x1b\[27;5;106~$/, action: ACTIONS.PAGE_DOWN },
+  { pattern: /^\x1b\[27;5;107~$/, action: ACTIONS.PAGE_UP },
+  { pattern: /^\x1b\[57422(?:;1)?u$/, action: ACTIONS.PAGE_DOWN },
+  { pattern: /^\x1b\[57421(?:;1)?u$/, action: ACTIONS.PAGE_UP },
+  { pattern: /^\x1b\[100;5(?::[12])?u$/, action: ACTIONS.HALF_DOWN },
+  { pattern: /^\x1b\[117;5(?::[12])?u$/, action: ACTIONS.HALF_UP },
+];
+// A release never acts: `:3` is the CSI-u event type for one, and xterm's
+// modifyOtherKeys carries the same suffix after the code.
+const RELEASE_RAW = /^(\x1b\[\d+(?:;\d+)*:3u|\x1b\[\d+(?:;\d+)+;3~)$/;
+
+// Names compare case-insensitively for multi-character ids (`pageDown` vs
+// `pagedown`), while a single letter stays exact so `j` can never answer for
+// the `J` scroll key.
+function sameName(left, right) {
+  const a = String(left);
+  const b = String(right);
+  if (a.length === 1 || b.length === 1) return a === b;
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+function actionForName(name) {
+  const text = String(name);
+  if (text === '') return null;
+  for (const rule of RULES) {
+    for (const candidate of rule.names) {
+      if (sameName(text, candidate)) return rule.action;
+    }
+  }
+  return null;
+}
+
+function released(helpers, data) {
+  try {
+    if (helpers && typeof helpers.isKeyRelease === 'function' && helpers.isKeyRelease(data) === true) return true;
+  } catch {
+    // A throwing classifier never claims a release; the raw check below decides.
+  }
+  return RELEASE_RAW.test(data);
+}
+
+// The host's own classifier answers first: its symbolic names are what the
+// terminal actually reported, and they are more reliable than any decoder we
+// could keep here. A single-letter candidate is never offered to the host
+// matcher — host matchers fold letter case, so asking about `J` would make a
+// lowercase `j` scroll — while `parseKey` still reads a real `J` exactly.
+function actionFromHost(helpers, data) {
+  try {
+    if (helpers && typeof helpers.matchesKey === 'function') {
+      for (const rule of RULES) {
+        for (const name of rule.names) {
+          if (name.length === 1) continue;
+          if (helpers.matchesKey(data, name) === true) return rule.action;
+        }
+      }
+    }
+  } catch {
+    // Fall through to the parser, then to the bounded table.
+  }
+  let parsed = null;
+  try {
+    if (helpers && typeof helpers.parseKey === 'function') parsed = helpers.parseKey(data);
+  } catch {
+    parsed = null;
+  }
+  return typeof parsed === 'string' ? actionForName(parsed) : null;
+}
+
+function actionFromRaw(data) {
+  const exact = RAW_ACTIONS.get(data);
+  if (exact) return exact;
+  for (const entry of RAW_PATTERNS) {
+    if (entry.pattern.test(data)) return entry.action;
+  }
+  return null;
+}
+
+/**
+ * The preview action one raw key payload asks for.
+ *
+ * @param {object|null} helpers the host TUI helpers (matchesKey/parseKey/
+ *   isKeyRelease/isKittyProtocolActive); any of them may be missing.
+ * @param {unknown} data the payload `handleInput` received.
+ * @returns {'page-down'|'page-up'|'half-down'|'half-up'|null} the action, or
+ *   null when this payload is not a preview scroll key.
+ */
+function resolveScrollAction(helpers, data) {
+  if (typeof data !== 'string' || data === '') return null;
+  if (FORBIDDEN_RAW.has(data)) return null;
+  if (released(helpers, data)) return null;
+  return actionFromHost(helpers, data) || actionFromRaw(data);
+}
+
+/**
+ * The footer entries for the scroll keys the readers share.
+ *
+ * The legend always names ctrl+j/k: it is the default pair the user asked to
+ * see, and the alternates (ctrl+shift+j/k, PgUp/PgDn, J/K, ctrl+d/u) keep
+ * working without a token. Only the first entry reaches the one collapsed
+ * `scroll` token, so the footer stays a single labelled target.
+ *
+ * @returns {Array<{text: string, short: string, priority: number}>} legend
+ *   entries in the shape the one-row footer compacts and drops from.
+ */
+function previewScrollKeys() {
+  const primary = { text: 'ctrl+j/k scroll', short: 'ctrl+j/k', priority: 52 };
+  return [
+    primary,
+    { text: 'PgUp/PgDn', short: 'PgUp/Dn', priority: 24 },
+    { text: 'ctrl+d/u half', short: 'ctrl+d/u', priority: 12 },
+  ];
+}
+
+module.exports = {
+  ACTIONS,
+  resolveScrollAction,
+  previewScrollKeys,
+};

package/lib/session-auto-name.js

@@ -0,0 +1,292 @@
+'use strict';
+// Automatic session naming from the ODD document being written
+// (odd/tasks/session-auto-name.md, D2-D7).
+//
+// Pure derivation, no I/O: the caller passes what a tool call touched, a
+// reader for the touched document when it has one, and whether that call was
+// a write, and gets back either the label to write or `null` for "leave the
+// session alone".
+//
+// The channel is the session NAME (`pi.setSessionName`), because Pi 1.3.0
+// exposes no subject/alias write (D7): the session record carries a single
+// `name`. The never-clobber guarantee (P3) therefore cannot come from a
+// channel choice, so it comes from PATTERN: the plugin may write only an
+// empty name or a name it can account for as its own (see
+// `isPluginSessionName`). Anything else was typed by a human and is
+// untouchable. The admitted consequence (D7) is that a human who names a
+// session exactly like a label the plugin would write owns a name the plugin
+// may later update.
+//
+// The label head is the document's own first level-1 heading (D2: the honest
+// source for what the session is about), and the filename slug is only the
+// fallback for a document with no readable heading.
+//
+// Input rels are the canonical `odd/<rel>` names the worktree capture already
+// produces, never raw filesystem paths: mapping a path to a document is path
+// logic that lives in one place already.
+
+// Document shape that names a session: `odd/tasks/<feature>.md`, where the
+// feature may be nested (`odd/tasks/perf/plan.md`).
+const ODD_TASKS_PREFIX = 'odd/tasks/';
+
+// Separator between the label head and the branch discriminator (D4). The
+// spaces make it a shape a human hand-typing a name rarely produces, and
+// they are what distinguishes the label from a human `fix@home`.
+const BRANCH_SEPARATOR = ' @ ';
+
+// A heading-sized label beyond this loses the rest of the words, cut at the
+// last word boundary so the name stays readable at a glance.
+const LABEL_MAX_CHARS = 48;
+
+// gentle-pi's ODD phase tool (L3). Its result says WHICH phase the session
+// moved to, never WHICH feature it is about, so the phase trigger cannot
+// derive anything: it re-applies what the session last derived from a write.
+// It is observable only as a `tool_result`, not a host event.
+const ODD_PHASE_TOOL_NAME = 'gentle_odd_phase';
+
+// A fallback feature is one or more `/`-separated segments using the
+// characters a document filename can carry, without whitespace. A branch is
+// any whitespace-free token — permissive on purpose, because a branch with an
+// unusual-but-legal character (say `#1`) must still be recognized as OUR
+// label on the next event, or a resumed session would freeze on it forever.
+const FEATURE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const BRANCH_TOKEN = /^\S+$/;
+
+// The tools whose call WRITES a document. Reading is context gathering: it
+// would make the name jump to whatever was opened last (P1), so `read` is
+// deliberately absent.
+const WRITE_TOOL_NAMES = new Set(['write', 'edit']);
+
+// The last ODD label each session applied, keyed by session id. In-module so
+// the phase trigger stays testable without the extension, and bounded so a
+// long-lived process that sees many sessions cannot grow without limit; only
+// the most recent sessions can still be alive and resumed.
+const SESSION_MEMORY_LIMIT = 100;
+const lastLabelBySession = new Map();
+
+function sessionKey(sessionId) {
+  return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+}
+
+function rememberLabel(sessionId, entry) {
+  const key = sessionKey(sessionId);
+  if (key === null) return;
+  // Re-inserting moves the session to the young end of the insertion order,
+  // so eviction always drops the least recently written session.
+  lastLabelBySession.delete(key);
+  lastLabelBySession.set(key, entry);
+  while (lastLabelBySession.size > SESSION_MEMORY_LIMIT) {
+    const oldest = lastLabelBySession.keys().next().value;
+    lastLabelBySession.delete(oldest);
+  }
+}
+
+function rememberedLabel(sessionId) {
+  const key = sessionKey(sessionId);
+  if (key === null) return null;
+  return lastLabelBySession.get(key) || null;
+}
+
+function isWriteToolName(name) {
+  return typeof name === 'string' && WRITE_TOOL_NAMES.has(name);
+}
+
+// `<feature>` for an `odd/tasks/<feature>.md` rel, else null. Rejects empty
+// segments, nested `.`/`..`, and any name carrying whitespace or characters a
+// feature document cannot have.
+function featureFromOddRel(rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return null;
+  if (!rel.startsWith(ODD_TASKS_PREFIX)) return null;
+  const tail = rel.slice(ODD_TASKS_PREFIX.length);
+  if (!tail.endsWith('.md')) return null;
+  const feature = tail.slice(0, -'.md'.length);
+  if (feature.length === 0) return null;
+  const segments = feature.split('/');
+  for (const segment of segments) {
+    if (segment === '.' || segment === '..' || !FEATURE_SEGMENT.test(segment)) return null;
+  }
+  return feature;
+}
+
+// The first `odd/tasks/<feature>.md` document of the call, or null. The
+// first one wins because a multi-document write has no natural order.
+function firstTaskDocument(rels) {
+  if (!Array.isArray(rels)) return null;
+  for (const rel of rels) {
+    const feature = featureFromOddRel(rel);
+    if (feature !== null) return { rel, feature };
+  }
+  return null;
+}
+
+// Cut to `max` characters at the last word boundary inside the cut, so a
+// truncated label ends with a whole word. A single word longer than `max`
+// has no boundary and is cut hard; anything short stays untouched.
+function truncateLabel(text, max) {
+  if (text.length <= max) return text;
+  const slice = text.slice(0, max);
+  const lastSpace = slice.lastIndexOf(' ');
+  return lastSpace > 0 ? slice.slice(0, lastSpace) : slice;
+}
+
+// The document's first level-1 ATX heading (`# ...`), trimmed with inner
+// whitespace collapsed and truncated for the label, or null when the text
+// carries none. A deeper heading (`## ...`) is a section title, not the
+// document's own heading, and never matches.
+function headingFromText(text) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    // ATX level-1 needs whitespace after the `#`; `##` and deeper are
+    // section titles, and `#hashtag` is prose, not a heading.
+    if (!/^#[ \t]/.test(line)) continue;
+    const body = line.slice(1).trim();
+    if (body.length === 0) continue;
+    return truncateLabel(body.replace(/\s+/g, ' '), LABEL_MAX_CHARS);
+  }
+  return null;
+}
+
+// The label head for a document: its heading when there is one, else the
+// filename slug. Deterministic for the same document, which is what keeps
+// repeated events idempotent.
+function labelHeadForDocument(feature, text) {
+  const heading = headingFromText(text);
+  return heading !== null ? heading : feature;
+}
+
+// Read the touched document through the caller's reader. Any failure — a
+// reader that throws, a missing file, a non-string result — is "no heading"
+// and falls back to the slug, never an error the naming path must handle.
+function readDocumentText(readDocument, rel) {
+  if (typeof readDocument !== 'function') return null;
+  try {
+    const text = readDocument(rel);
+    return typeof text === 'string' ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+// D4: the branch suffix is what keeps two concurrent forks of the same
+// feature apart, since the worktree branch is already unique. A branch the
+// caller cannot supply (an odd registry entry without one) degrades to the
+// bare label head, which is still a label the plugin owns.
+function sessionNameForFeature(feature, branch) {
+  if (typeof branch === 'string' && BRANCH_TOKEN.test(branch)) {
+    return `${feature}${BRANCH_SEPARATOR}${branch}`;
+  }
+  return feature;
+}
+
+function isFeatureName(name) {
+  if (typeof name !== 'string' || name.length === 0) return false;
+  const segments = name.split('/');
+  return segments.every((segment) => segment !== '.' && segment !== '..' && FEATURE_SEGMENT.test(segment));
+}
+
+// The ownership test (D7), widened for heading labels: a name counts as the
+// plugin's own when ANY of these holds.
+//   (a) it is the label this session already applied (the memory below),
+//       which is what lets the phase trigger reuse it;
+//   (b) it ends with ` @ <branch>` for THIS worktree's branch — the property
+//       that survives a resume without in-memory state, since the branch
+//       suffix is applied on every write;
+//   (c) it is the plain feature slug from the filename, i.e. what earlier
+//       versions wrote before heading labels existed;
+//   (d) it is the document's current heading.
+// Called with no context it keeps the original contract: exactly the two
+// shapes earlier versions wrote (`<feature>` and `<feature> @ <branch>`).
+function isPluginSessionName(name, context) {
+  if (typeof name !== 'string' || name.length === 0) return false;
+  const { branch, feature, documentLabel, appliedLabel } = context || {};
+  if (typeof appliedLabel === 'string' && appliedLabel.length > 0 && name === appliedLabel) return true;
+  if (typeof documentLabel === 'string' && documentLabel.length > 0 && name === documentLabel) return true;
+  const at = name.indexOf(BRANCH_SEPARATOR);
+  if (at === -1) {
+    if (typeof feature === 'string' && feature.length > 0 && name === feature) return true;
+    return isFeatureName(name);
+  }
+  const head = name.slice(0, at);
+  const tail = name.slice(at + BRANCH_SEPARATOR.length);
+  if (head.length === 0 || !BRANCH_TOKEN.test(tail)) return false;
+  if (typeof branch === 'string' && branch.length > 0 && tail === branch) return true;
+  return isFeatureName(head);
+}
+
+// May the plugin write over `name`? An unnamed session (empty, or no name
+// entry at all — `getSessionName()` returns undefined) is adoptable; every
+// other name must be the plugin's own.
+function canAdoptSessionName(name, context) {
+  if (name === undefined || name === null) return true;
+  if (typeof name !== 'string') return false;
+  return name.length === 0 || isPluginSessionName(name, context);
+}
+
+// The label for a tool call that touched `rels`, or null when the call is
+// not a WRITE to an `odd/tasks/<feature>.md` document. No ownership is
+// decided here; `planSessionRename` owns that.
+function autoNameForToolCall({ rels, isWrite, branch, readDocument } = {}) {
+  if (isWrite !== true) return null;
+  const match = firstTaskDocument(rels);
+  if (match === null) return null;
+  const head = labelHeadForDocument(match.feature, readDocumentText(readDocument, match.rel));
+  return sessionNameForFeature(head, branch);
+}
+
+// The single decision the write wiring needs. Returns the name to write, or
+// null for "touch nothing", which covers three cases: the call did not write
+// an ODD task document, the current name was chosen by a human, and the
+// derived label is already the current name — the last one is what makes
+// running this on every pipeline event idempotent instead of a stream of host
+// writes. The derived label is remembered per session whether or not it was
+// written, so a later phase transition can re-apply it.
+function planSessionRename({ rels, isWrite, branch, currentName, sessionId, readDocument } = {}) {
+  if (isWrite !== true) return null;
+  const match = firstTaskDocument(rels);
+  if (match === null) return null;
+  const head = labelHeadForDocument(match.feature, readDocumentText(readDocument, match.rel));
+  const label = sessionNameForFeature(head, branch);
+  const previous = rememberedLabel(sessionId);
+  const adoptable = canAdoptSessionName(currentName, {
+    branch,
+    feature: match.feature,
+    documentLabel: head,
+    appliedLabel: previous === null ? undefined : previous.label,
+  });
+  rememberLabel(sessionId, { label, head, branch });
+  if (!adoptable || label === currentName) return null;
+  return label;
+}
+
+// The phase trigger: an ODD phase transition with no feature of its own
+// re-applies the label this session last derived from a write. Returns null
+// for "touch nothing" when the session never wrote an ODD document, when the
+// current name is a human's, or when the label is already applied.
+function planPhaseSessionRename({ sessionId, branch, currentName } = {}) {
+  const previous = rememberedLabel(sessionId);
+  if (previous === null) return null;
+  if (!canAdoptSessionName(currentName, { branch, appliedLabel: previous.label })) return null;
+  const effectiveBranch = typeof branch === 'string' && branch.length > 0 ? branch : previous.branch;
+  const label = sessionNameForFeature(previous.head, effectiveBranch);
+  if (label === currentName) return null;
+  rememberLabel(sessionId, { label, head: previous.head, branch: effectiveBranch });
+  return label;
+}
+
+module.exports = {
+  ODD_TASKS_PREFIX,
+  BRANCH_SEPARATOR,
+  LABEL_MAX_CHARS,
+  ODD_PHASE_TOOL_NAME,
+  autoNameForToolCall,
+  featureFromOddRel,
+  headingFromText,
+  isPluginSessionName,
+  canAdoptSessionName,
+  isWriteToolName,
+  labelHeadForDocument,
+  planSessionRename,
+  planPhaseSessionRename,
+  sessionNameForFeature,
+};

package/lib/session-worktree-register.js

@@ -0,0 +1,62 @@
+'use strict';
+// Session worktree registration for the worktree tools (customize-command
+// T41/S50).
+//
+// gentle-shell registers a host tool named `session_worktree_register`
+// (extensions/gentle-shell.ts:1875, default `direct` exposure so it is
+// callable while active): it validates the path through its per-session
+// SessionWorktreeRegistry (same-git-clone check, current-session check)
+// and appends a `gentle-pi.session-worktree/v1` custom entry to the
+// session file, which is what puts the checkout inside the `/gentle:changes`
+// scope (`sessionChangeRoots` unions those entries with captured evidence).
+// Merely creating a checkout elsewhere never updates the creating
+// session's scope — the registry only auto-registers the session's own
+// cwd at `session_start` — so the create tool calls this explicitly.
+//
+// The host API is `ctx.executeTool(name, args)` (Pi 1.3.0,
+// dist/core/extensions/types.d.ts:280): it never rejects for tool
+// failures (unknown tool, validation error, blocked call and thrown
+// errors all come back as `isError: true`), and `ctx.tools`
+// (types.d.ts:271) lists the tools it can call. Availability therefore
+// means: `ctx.executeTool` is a function AND `ctx.tools` names the
+// tool. Everything routes through the calling tool's context, so it is
+// injectable in tests via a ctx double and no gentle-shell module is
+// ever imported here.
+
+const SESSION_WORKTREE_TOOL = 'session_worktree_register';
+
+// True only when the host tool is actually available on this context:
+// callable through `ctx.executeTool` and listed in `ctx.tools`. A
+// context without a tool list (older doubles) counts as unavailable.
+function isSessionWorktreeToolAvailable(ctx) {
+  try {
+    if (!ctx || typeof ctx.executeTool !== 'function') return false;
+    const tools = ctx.tools;
+    if (!Array.isArray(tools)) return false;
+    return tools.some((tool) => tool && tool.name === SESSION_WORKTREE_TOOL);
+  } catch {
+    return false;
+  }
+}
+
+// Register `checkoutPath` on the current session. Resolves to true only
+// when the host tool ran and reported success; every other outcome —
+// unavailable tool, empty path, `isError`, thrown error — resolves to
+// false and never rejects, so the caller can skip silently.
+async function registerSessionWorktree(ctx, checkoutPath) {
+  if (!isSessionWorktreeToolAvailable(ctx)) return false;
+  if (typeof checkoutPath !== 'string' || checkoutPath.length === 0) return false;
+  try {
+    const outcome = await ctx.executeTool(SESSION_WORKTREE_TOOL, { path: checkoutPath });
+    if (!outcome || outcome.isError === true) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  SESSION_WORKTREE_TOOL,
+  isSessionWorktreeToolAvailable,
+  registerSessionWorktree,
+};