@brainervirus/workit-core 8.8.0 → 8.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.8.0",
+  "version": "8.9.1",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/task-context.ts

@@ -73,11 +73,20 @@ type CompactDecision = {
   digest: string;
   choice: string;
   references: CompactReference[];
+  /** Where an inherited decision was recorded ("branch develop"); absent for the task's own. */
+  origin?: string;
 };
 type CompactMethod = Pick<SelectedMethod, "id" | "assurance"> & { reason: string };
+/** Decisions of a task the current one inherits from (its base branch's task). */
+export type InheritedDecisions = {
+  origin: string;
+  taskId: string;
+  decisions: TaskView["task"]["decisions"];
+};
 export type CompactTaskContext = {
   objective: string;
-  status: TaskView["task"]["status"];
+  /** Null when the checkout has no task yet and only inherited decisions apply. */
+  status: TaskView["task"]["status"] | null;
   decisions: CompactDecision[];
   methods: CompactMethod[];
   gaps: string[];
@@ -128,54 +137,83 @@ const compactReference = (ref: Ref): CompactReference => {
   return { kind: ref.kind };
 };
 
-export function compactTaskContext(view: TaskView): string {
-  const decisions: CompactDecision[] = view.task.decisions
-    .slice()
-    .toSorted((left, right) => {
-      const leftAt = compactTimestamp(left.recordedAt);
-      const rightAt = compactTimestamp(right.recordedAt);
-      if (leftAt !== rightAt) return leftAt > rightAt ? -1 : 1;
-      return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
-    })
-    .slice(0, COMPACT_MAX_ITEMS)
-    .map((entry) => ({
-      id: entry.id,
-      purpose: entry.data.purpose,
-      status: entry.data.response,
-      digest: entry.data.digest,
-      choice:
-        compactDecisionChoice(entry) ||
-        `task.inspect taskId=${view.task.id} view=full; decision=${entry.id}`,
-      references: entry.data.binding.contentRefs.slice(0, 1).map(compactReference),
-    }));
-  const methods: CompactMethod[] = view.task.policy
+type TaskDecision = TaskView["task"]["decisions"][number];
+const newestDecisionFirst = (left: TaskDecision, right: TaskDecision): number => {
+  const leftAt = compactTimestamp(left.recordedAt);
+  const rightAt = compactTimestamp(right.recordedAt);
+  if (leftAt !== rightAt) return leftAt > rightAt ? -1 : 1;
+  return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+};
+/**
+ * The task's own decisions (newest first), then the ones it inherits (origin
+ * set; the engine passes only unrevoked ones), at most COMPACT_MAX_ITEMS.
+ */
+const compactDecisions = (
+  sources: Array<{ origin: string | null; taskId: string; decisions: TaskDecision[] } | null>,
+): CompactDecision[] =>
+  sources
+    .flatMap((source) =>
+      source
+        ? source.decisions.toSorted(newestDecisionFirst).map((entry) => ({
+            id: entry.id,
+            purpose: entry.data.purpose,
+            status: entry.data.response,
+            digest: entry.data.digest,
+            choice:
+              compactDecisionChoice(entry) ||
+              `task.inspect taskId=${source.taskId} view=full; decision=${entry.id}`,
+            references: entry.data.binding.contentRefs.slice(0, 1).map(compactReference),
+            // Undefined (dropped from the JSON) for the task's own decisions.
+            origin: source.origin ?? undefined,
+          }))
+        : [],
+    )
+    .slice(0, COMPACT_MAX_ITEMS);
+
+/**
+ * The compact context of `view`'s task plus the decisions it inherits; with
+ * a null `view` (the branch has no task of its own yet) only the inherited
+ * decisions. Stale evidence is one counted gap with the command that lists it.
+ */
+export function compactTaskContext(
+  view: TaskView | null,
+  inherited: InheritedDecisions | null = null,
+): string {
+  const decisions = compactDecisions([
+    view && { origin: null, taskId: view.task.id, decisions: view.task.decisions },
+    inherited,
+  ]);
+  const methods: CompactMethod[] = view?.task.policy
     ? selectMethods(view.task.policy, view.capabilities).map((method) => ({
         id: method.id,
         assurance: method.assurance,
         reason: compactText(method.reason, COMPACT_TEXT_BYTES) ?? "",
       }))
     : [];
+  const stale = view?.evidence.filter((entry) => entry.status === "stale").length;
   const gaps = Array.from(
     new Set([
-      ...view.evidence
-        .filter((entry) => entry.status === "stale")
-        .map((entry) => `stale evidence: ${entry.evidenceId}`),
-      ...view.requirements
+      ...(stale
+        ? [`stale evidence: ${stale}; workit task inspect --task ${view.task.id} --view full`]
+        : []),
+      ...(view?.requirements ?? [])
         .filter((entry) => entry.status !== "satisfied")
         .map((entry) => entry.reason),
-      ...view.task.progress.blockers.map((entry) => entry.reason),
+      ...(view?.task.progress.blockers ?? []).map((entry) => entry.reason),
     ]),
   )
     .toSorted()
     .slice(0, COMPACT_MAX_ITEMS)
     .map((gap) => compactText(gap, COMPACT_TEXT_BYTES)!);
   const context: CompactTaskContext = {
-    objective: compactText(view.task.intent.data.objective, COMPACT_TEXT_BYTES) ?? "",
-    status: view.task.status,
+    objective: view
+      ? (compactText(view.task.intent.data.objective, COMPACT_TEXT_BYTES) ?? "")
+      : "no task on this branch yet",
+    status: view?.task.status ?? null,
     decisions,
     methods,
     gaps,
-    nextAction: compactText(view.task.progress.nextAction, COMPACT_TEXT_BYTES),
+    nextAction: compactText(view?.task.progress.nextAction ?? null, COMPACT_TEXT_BYTES),
   };
   let encoded = JSON.stringify(context);
   while (

package/src/core/task-engine.ts

@@ -68,6 +68,7 @@ import { defaultLockTimeout } from "./store-lock";
 import {
   compactTaskContext,
   exportDigest,
+  type InheritedDecisions,
   reconcileResume as reconcileResumeContext,
   type ResumeReconciliation,
 } from "./task-context";
@@ -389,6 +390,18 @@ const TASK_SCOPED_ACTIONS: ReadonlySet<string> = new Set([
   "worker.cancel",
   "state.export",
 ]);
+/** Worker actions that name their worker: they resolve to that worker's task. */
+const WORKER_ADDRESSED_ACTIONS: ReadonlySet<string> = new Set(["worker.cancel", "worker.report"]);
+/**
+ * The exact CLI command that runs worker `request` (cancel or report, with a
+ * valid workerId) on `taskId`, so a retry never depends on the branch.
+ */
+const workerCommand = (taskId: string, request: unknown): string => {
+  const { action, workerId, reason, report } = request as Record<string, unknown>;
+  const rest = JSON.stringify({ reason, report });
+  const payload = rest === "{}" ? "" : ` --payload '${rest.replace(/'/gu, "'\\''")}'`;
+  return `workit worker ${String(action)} ${String(workerId)} --task ${taskId}${payload}`;
+};
 /** Recording actions that create the implicit task on first use. */
 const CREATING_ACTIONS: ReadonlySet<string> = new Set([
   "task.revise",
@@ -711,6 +724,24 @@ export class WorkitCore {
     if (!TASK_SCOPED_ACTIONS.has(action)) return success(null, null, request);
     const root = this.contextRootError();
     if (!root.ok) return root;
+    // A worker belongs to the task it was assigned on, whatever branch is
+    // checked out now (#264): worker.cancel/report follow the named worker,
+    // a helper's own calls follow its worker id.
+    const addressed = WORKER_ADDRESSED_ACTIONS.has(action);
+    // A missing or malformed id is invalid_input (from taskForWorker).
+    const workerId: unknown = addressed
+      ? (value as { workerId?: unknown }).workerId
+      : (this.context.workerId ?? null);
+    if (workerId !== null) {
+      const owner = this.store.taskForWorker(workerId);
+      if (!owner.ok) return owner;
+      if (owner.data) return success(null, null, { ...request, taskId: owner.data });
+      if (addressed)
+        return failure(
+          "not_found",
+          `worker ${workerId as string} is on no open task; find its task with \`workit task status --all\`, then run \`${workerCommand("<task-id>", request)}\``,
+        );
+    }
     const create = CREATING_ACTIONS.has(action) && (this.context.workerId ?? null) === null;
     const found = this.store.implicitTask({
       provenance: provenance(this.context),
@@ -1605,7 +1636,16 @@ export class WorkitCore {
     const resolved = this.implicitTask("worker", request);
     if (!resolved.ok) return resolved;
     const value = resolved.data;
-    return this.retryOmittedRevisions(value, () => this.workerOnce(value));
+    const result = this.retryOmittedRevisions(value, () => this.workerOnce(value));
+    // A cancel/report whose task was resolved from the worker id names the
+    // exact command for that task (every host and the CLI see the same text).
+    const { action, taskId } = (value ?? {}) as { action?: unknown; taskId?: unknown };
+    return result.ok ||
+      (request as { taskId?: unknown } | null)?.taskId !== undefined ||
+      typeof taskId !== "string" ||
+      !WORKER_ADDRESSED_ACTIONS.has(`worker.${String(action)}`)
+      ? result
+      : { ...result, error: `${result.error}; run \`${workerCommand(taskId, value)}\`` };
   }
 
   private workerOnce(request: unknown): Result<Entry<Worker>> {
@@ -1892,9 +1932,31 @@ export class WorkitCore {
    * judged against the last recorded candidate, and live staleness is
    * detected by evidence, close, resume, and full inspection, which capture.
    */
-  compactContext(taskId: string, freshness?: Freshness): Result<string> {
+  compactContext(
+    taskId: string | null,
+    freshness?: Freshness,
+    /** The base branch's task (TaskStore.originTaskEntry), whose decisions are inherited. */
+    origin: { origin: string; taskId: string } | null = null,
+  ): Result<string> {
     const root = this.contextRootError();
     if (!root.ok) return root;
+    const base = origin && this.store.readStoreTask(origin.taskId);
+    const inherited: InheritedDecisions | null =
+      base?.ok && base.data
+        ? {
+            origin: origin!.origin,
+            taskId: base.data.id,
+            // A revoked decision no longer applies to anything cut from the base.
+            decisions: base.data.decisions.filter((entry) => entry.data.revoked === null),
+          }
+        : null;
+    // No task of its own yet: only what the branch inherits.
+    if (taskId === null)
+      return success(
+        null,
+        null,
+        inherited?.decisions.length ? compactTaskContext(null, inherited) : "",
+      );
     const task = this.store.readTask(taskId);
     if (!task.ok) return task;
     const helper = this.helperTaskGuard(task.data, true);
@@ -1902,7 +1964,7 @@ export class WorkitCore {
     // Per-turn path: the cheap worktree signal, never the object-writing tree hash.
     const view = this.view(task.data, false, freshness ?? signalFreshness(this.store.root));
     if (!view.ok) return view;
-    return success(view.revision, view.workspaceRevision, compactTaskContext(view.data));
+    return success(view.revision, view.workspaceRevision, compactTaskContext(view.data, inherited));
   }
 
   private view(

package/src/core/task-store.ts

@@ -314,6 +314,70 @@ const isNewerVersion = (candidate: string, current: string): boolean => {
 };
 const validId = (value: string): boolean =>
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
+
+const readText = (file: string): string => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+/** `<old> <new> <ident> <unix seconds> <tz>\t<message>`: new sha, seconds, message. */
+const REFLOG_LINE = /^[0-9a-f]+ ([0-9a-f]+) .* (\d+) [+-]\d{4}\t(.*)$/u;
+
+/**
+ * The branch `branch` was cut from, read from git's reflogs (no git process).
+ * Only the branch log's first line counts, and only when it is the creation
+ * entry "branch: Created from <start>": an expired, rewritten or missing log
+ * says nothing. A branch created from HEAD takes
+ * the worktree HEAD log's checkout made by that creation (same new sha, same
+ * or next second) onto the branch or one of its earlier names (`aliases`, it
+ * may have been renamed since). A remote start (`origin/develop`) is
+ * returned as written.
+ */
+const branchStart = (
+  location: StoreLocation,
+  branch: string,
+  aliases: readonly string[],
+): string | null => {
+  const first = readText(
+    path.join(path.dirname(location.dir), "logs", "refs", "heads", branch),
+  ).split("\n", 1)[0];
+  // A "Created from" message only ever starts a log (git deletes the log
+  // with the branch), so the first line alone decides.
+  const created = REFLOG_LINE.exec(first);
+  const start = created && /^branch: Created from (\S+)$/u.exec(created[3])?.[1];
+  if (!created || !start) return null;
+  if (start !== "HEAD") return start;
+  if (!location.git) return null;
+  for (const line of readText(path.join(location.git.gitDir, "logs", "HEAD")).split("\n")) {
+    const entry = REFLOG_LINE.exec(line);
+    const moved = entry && /^checkout: moving from (\S+) to (\S+)$/u.exec(entry[3]);
+    const seconds = entry ? Number(entry[2]) - Number(created[2]) : -1;
+    if (
+      moved &&
+      entry[1] === created[1] &&
+      seconds >= 0 &&
+      seconds <= 1 &&
+      aliases.includes(moved[2])
+    )
+      return moved[1];
+  }
+  return null;
+};
+
+/** Whether `ref` (`refs/remotes/origin/develop`) exists, loose or packed. */
+const refExists = (common: string, ref: string): boolean =>
+  fs.existsSync(path.join(common, ref)) ||
+  readText(path.join(common, "packed-refs")).includes(` ${ref}\n`);
+
+/** Resolved bases per checkout and branch, reused while the reflogs they came
+ * from are unchanged (one entry per branch a process looked at). */
+const origins = new Map<
+  string,
+  { signature: string; name: string | null; renames: ReturnType<typeof branchRenames> }
+>();
 export const sameDirectoryIdentity = (left: string, right: string): boolean => {
   if (!path.isAbsolute(left) || !path.isAbsolute(right)) return false;
   const normalizedLeft = path.resolve(left);
@@ -658,6 +722,94 @@ export class TaskStore {
     return success(null, null, { key: key.data, bound: bound.data });
   }
 
+  /**
+   * The open task of this checkout that worker `workerId` is assigned to,
+   * whichever branch it is bound to: worker commands follow the worker, not
+   * the branch checked out now (#264). Null when no open task has it.
+   */
+  taskForWorker(workerId: unknown): Result<Id | null> {
+    if (typeof workerId !== "string" || !validId(workerId))
+      return failure(
+        "invalid_input",
+        "needs a worker id: `workit worker cancel|report <workerId>`",
+      );
+    const listed = this.listTaskIndex();
+    if (!listed.ok) return listed;
+    for (const entry of listed.data) {
+      if (entry.status === "closed") continue;
+      const loaded = this.load(entry.id);
+      if (!loaded.ok) return loaded;
+      if (loaded.data?.record.workers.some((worker) => worker.id === workerId))
+        return success(null, null, entry.id);
+    }
+    return success(null, null, null);
+  }
+
+  /**
+   * The open task whose decisions the current branch inherits: the task of
+   * the branch it was cut from (`origin/develop` counts as `develop`), in any
+   * checkout of this repository, labelled with its origin ("branch develop").
+   * Null off a branch, or when git's reflogs do not name a base.
+   */
+  originTaskEntry(): Result<{ origin: string; entry: TaskIndexEntry } | null> {
+    const key = this.currentKey();
+    const location = this.location();
+    const branch = key.ok ? key.data.branch : null;
+    if (!branch || !location.ok) return success(null, null, null);
+    const common = path.dirname(location.data.dir);
+    const heads = path.join(common, "logs", "refs", "heads");
+    const headLog = location.data.git ? path.join(location.data.git.gitDir, "logs", "HEAD") : "";
+    // Per-turn path: reading a long HEAD log and every branch log costs tens
+    // of ms, so the resolution is reused until one of these files changes.
+    const signatures = [
+      path.join(heads, branch),
+      headLog,
+      heads,
+      path.join(common, "packed-refs"),
+    ].map((file) => fileSignature(file) ?? "-");
+    const slot = `${location.data.dir}\0${headLog}\0${branch}`;
+    let resolved = origins.get(slot);
+    if (resolved?.signature !== signatures.join("|")) {
+      const renames = branchRenames(location.data);
+      // The branch's earlier names, newest first: a rename keeps its log.
+      const aliases = [branch];
+      for (const rename of renames.toReversed())
+        if (rename.to === aliases.at(-1)) aliases.push(rename.from);
+      const start = branchStart(location.data, branch, aliases);
+      const slash = start?.indexOf("/") ?? -1;
+      // `origin/develop` is the remote's `develop`: strip the remote only for
+      // a remote-tracking ref or a configured remote, never for a local
+      // branch or tag that has a slash in its name.
+      const remote =
+        slash > 0 &&
+        !refExists(common, `refs/heads/${start}`) &&
+        (refExists(common, `refs/remotes/${start}`) ||
+          readText(path.join(common, "config")).includes(`[remote "${start!.slice(0, slash)}"]`));
+      const name = start && (remote ? start.slice(slash + 1) : start);
+      // Logs only grow (their size is in the signature), so no racy check.
+      resolved = {
+        signature: signatures.join("|"),
+        name: name && !aliases.includes(name) ? name : null,
+        renames,
+      };
+      origins.set(slot, resolved);
+    }
+    const entry = resolved.name ? this.openTasksForKey(resolved.name, resolved.renames) : null;
+    if (entry && !entry.ok) return entry;
+    return success(
+      null,
+      null,
+      entry?.data[0] ? { origin: `branch ${resolved.name}`, entry: entry.data[0] } : null,
+    );
+  }
+
+  /** The record of an indexed task (`taskId` from the index) in any checkout of
+   * this store: read-only, no binding check. */
+  readStoreTask(taskId: Id): Result<TaskRecord | null> {
+    const loaded = this.load(taskId);
+    return loaded.ok ? success(null, null, loaded.data?.record ?? null) : loaded;
+  }
+
   // -------------------------------------------------------------------------
   // writes
 
@@ -1442,11 +1594,14 @@ export class TaskStore {
    * task follows its branch through `git branch -m`: it counts for the new
    * name, and a branch created later under the old name starts fresh.
    */
-  private openTasksForKey(key: string): Result<TaskIndexEntry[]> {
+  private openTasksForKey(
+    key: string,
+    known?: ReturnType<typeof branchRenames>,
+  ): Result<TaskIndexEntry[]> {
     const all = this.listStoreIndex();
     if (!all.ok) return all;
-    const location = this.location();
-    const renames = location.ok ? branchRenames(location.data) : [];
+    const location = known ? null : this.location();
+    const renames = known ?? (location?.ok ? branchRenames(location.data) : []);
     return success(
       null,
       null,

package/src/git/session-hook.ts

@@ -0,0 +1,521 @@
+// The prepare-commit-msg hook that gives a plain `git commit` the
+// `Workit-Session:` trailer `workit git commit` adds (D18), for agents that
+// cannot run `workit git` (a Claude Code worktree-isolated subagent).
+// `workit doctor` reports it; `workit doctor --fix` installs it, in a Workit
+// workspace only.
+//
+// - One source of truth: the trailer logic is SESSION_TRAILER_SCRIPT, written
+//   to `<git-common-dir>/workit/session-trailer.sh` (Workit-owned, never a hook
+//   slot, never the working tree). The hook Workit installs, and every line a
+//   user is told to add to a hook Workit does not own, is the same one-liner
+//   that runs it with the hook's arguments.
+// - Slot: prepare-commit-msg, not commit-msg. Git runs it for -m/-F, amend,
+//   merge and squash, even with --no-verify, and before commit-msg, so a
+//   commitlint there sees the trailer. commit-msg stays the user's.
+// - Where: `git rev-parse --git-path hooks`, so core.hooksPath is honoured.
+//   Workit writes only an empty slot or its own hook. Another tool's hook in
+//   the slot (husky, lefthook, a hand-written one) is never renamed, wrapped or
+//   edited: the state is `blocked` and `manual` names the line to add there;
+//   once that hook (or husky script, or lefthook config) runs the helper, the
+//   state is `manual`.
+//   A hooks directory outside the repository (a global core.hooksPath), or one
+//   in the working tree that git does not ignore, gets no hook either.
+// - The session comes from the same variables as host-session.ts: WORKIT_SESSION_ID
+//   (unless WORKIT_HOST names another host than the shell's own), else
+//   OPENCODE_SESSION_ID, PI_SESSION_ID or CODEX_THREAD_ID. The message is left
+//   unchanged with no session or an unsafe id; for a plain editor commit (no
+//   message source: the trailer would sit in the buffer, and a user who empties
+//   it would commit a trailer-only message instead of aborting); for a
+//   template (git aborts an unedited one); for a comment-only message; and in a
+//   rebase or cherry-pick replaying commits that keep their own trailers.
+// - `--if-exists addIfDifferent`: the same session's trailer is never repeated;
+//   another session that amends adds its own, as `workit git commit --amend` does.
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { GIT_TIMEOUTS } from "./rev";
+
+export const SESSION_HOOK_NAME = "prepare-commit-msg";
+export const SESSION_HOOK_MARKER = "# workit-session-trailer-hook";
+/** The helper under the git common dir that holds the trailer logic. */
+const HELPER = ["workit", "session-trailer.sh"] as const;
+/** Left by an unreleased build that chained commit-msg; reported, never used. */
+const LEGACY_CHAINED = "commit-msg.workit-chained";
+
+// LF only: Git for Windows runs hooks with its own sh, which reads LF scripts.
+export const SESSION_TRAILER_SCRIPT = `#!/bin/sh
+# Workit (https://github.com/BrainerVirus/workit) wrote this file with
+# \`workit doctor --fix\`. A prepare-commit-msg hook runs it with its own
+# arguments to add a Workit-Session trailer to commits made in an agent session.
+# Not a hook itself; delete it together with the line that runs it.
+# lefthook passes a missing argument as its literal placeholder.
+case "\${2-}" in "" | "{2}" | template) exit 0 ;; esac
+gitdir=$(git rev-parse --git-dir) || exit 0
+if [ -d "$gitdir/rebase-merge" ] || [ -d "$gitdir/rebase-apply" ] || [ -f "$gitdir/CHERRY_PICK_HEAD" ]; then
+  exit 0
+fi
+trim() { printf '%s' "$1" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'; }
+inner=$(trim "\${OPENCODE_SESSION_ID-}"); inner_host=opencode
+if [ -z "$inner" ]; then inner=$(trim "\${PI_SESSION_ID-}"); inner_host=pi; fi
+if [ -z "$inner" ]; then inner=$(trim "\${CODEX_THREAD_ID-}"); inner_host=codex; fi
+[ -n "$inner" ] || inner_host=
+declared=$(trim "\${WORKIT_HOST-}")
+family=$(printf '%s' "$declared" | sed 's/_cli$//;s/_desktop$//')
+session=$inner
+if [ "\${WORKIT_SESSION_ID+set}" = set ]; then
+  if [ -z "$inner" ] || [ -z "$declared" ] || [ "$family" = "$inner_host" ]; then
+    session=$(trim "$WORKIT_SESSION_ID")
+  fi
+fi
+[ -n "$session" ] || exit 0
+[ \${#session} -le 128 ] || exit 0
+case "$session" in *[!A-Za-z0-9_.:@/+-]*) exit 0 ;; esac
+add_trailer() {
+  [ -f "$1" ] && [ -r "$1" ] || return 0
+  body=$(sed '/^# -\\{24\\} >8 -\\{24\\}$/,$d' "$1" | git stripspace --strip-comments)
+  [ -n "$body" ] || return 0
+  # A merge message has no final newline; interpret-trailers would glue the
+  # trailer to the subject line.
+  [ -z "$(tail -c 1 "$1")" ] || printf '\\n' >> "$1"
+  git -c trailer.separators=: -c trailer.where=end interpret-trailers --in-place \\
+    --no-divider --if-exists addIfDifferent --trailer "Workit-Session: $session" "$1" || return 0
+}
+# $1 is the message file. lefthook cannot quote a path it pastes in, so its
+# job passes '' and the file is found here: git hands the hook COMMIT_EDITMSG,
+# except \`git merge\`, which hands it MERGE_MSG. With source "merge" both are
+# updated: the one git did not hand over is stale or removed after the commit.
+case "\${1-}" in "" | "{1}") ;; *) add_trailer "$1"; exit 0 ;; esac
+add_trailer "$(git rev-parse --git-path COMMIT_EDITMSG)"
+[ "$2" != merge ] || add_trailer "$(git rev-parse --git-path MERGE_MSG)"
+exit 0
+`;
+
+/**
+ * The line that runs the helper from a shell prepare-commit-msg hook, with the
+ * hook's own arguments. Hooks run at the top of the work tree, where the
+ * relative common dir resolves. A clone without the helper (a teammate who
+ * never ran `--fix`, while the line sits in a committed husky hook) runs
+ * nothing and prints nothing.
+ */
+export const manualTrailerLine = (): string =>
+  `h="$(git rev-parse --git-common-dir 2>/dev/null)/${HELPER.join("/")}"; [ ! -f "$h" ] || sh "$h" "$@" || true`;
+
+/**
+ * The same for a lefthook `run:`, with no double quote in it: on Windows
+ * lefthook starts `"sh" -c "<run>"` as one raw command line, so a `"` in the
+ * run ends that argument early. `set -f` and an empty IFS keep the unquoted
+ * `$h` one word (a path with spaces) and unglobbed. lefthook pastes `{1}` in
+ * raw, and from a linked worktree it is an absolute path that may hold a
+ * space or a quote, which no quoting survives; so the job passes '' and the
+ * helper finds the message file itself. `{2}` and `{3}` are a source word and
+ * a sha, safe unquoted.
+ */
+export const lefthookTrailerRun = (): string =>
+  `set -f; IFS=; h=$(git rev-parse --git-common-dir 2>/dev/null)/${HELPER.join("/")}; [ ! -f $h ] || sh $h '' {2} {3} || true`;
+
+/** What marks a hook or config that already runs the helper. */
+const HELPER_REF = HELPER.join("/");
+
+export const SESSION_HOOK_SCRIPT = `#!/bin/sh
+${SESSION_HOOK_MARKER} v4
+# Workit (https://github.com/BrainerVirus/workit) installed this hook with
+# \`workit doctor --fix\`: it runs Workit's session-trailer helper, which adds a
+# Workit-Session trailer to commits made in an agent session. To remove it,
+# delete this file.
+${manualTrailerLine()}
+`;
+
+export type SessionHookState =
+  /** Not inside a git work tree, or git is unavailable. */
+  | "not_git"
+  /** The current Workit hook and helper are installed. */
+  | "installed"
+  /** An older Workit hook, or a missing or older helper; --fix rewrites them. */
+  | "outdated"
+  /** The slot is empty; --fix installs the hook. */
+  | "missing"
+  /** --fix will not write the hook; `reason` says why and `manual` what to do instead. */
+  | "blocked"
+  /** Another tool's hook or config already runs the helper (`via`, `manualTarget`). */
+  | "manual";
+
+/** Who owns the slot when it is blocked by another hook. */
+export type HookOwner = "husky" | "lefthook" | "other";
+
+export type SessionHookStatus = {
+  state: SessionHookState;
+  hooksDir: string | null;
+  hookPath: string | null;
+  /** The helper the hook and the manual line run. */
+  helperPath: string | null;
+  /** Whether the helper on disk is the current script. */
+  helperCurrent: boolean;
+  owner?: HookOwner;
+  reason?: string;
+  /** The manual fix when --fix cannot install the hook. */
+  manual?: string;
+  /** Where the manual line goes (or already is): a husky script, a lefthook config, a hook. */
+  manualTarget?: string;
+  /** For `manual`: who runs the helper. */
+  via?: "husky" | "lefthook" | "existing hook";
+  /** Files left by the unreleased commit-msg design, with how to recover. */
+  leftover?: string;
+};
+
+const run = (cwd: string, args: string[], env: NodeJS.ProcessEnv) => {
+  const r = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return { ok: r.status === 0, out: (r.stdout ?? "").trim() };
+};
+
+const inside = (child: string, parent: string): boolean => {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+};
+
+const readText = (file: string): string | null => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+const exists = (file: string): boolean => {
+  try {
+    lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const LEFTHOOK_CONFIGS = [
+  "lefthook.yml",
+  "lefthook.yaml",
+  ".lefthook.yml",
+  ".lefthook.yaml",
+  "lefthook.json",
+  "lefthook.toml",
+];
+
+const lefthookConfig = (top: string): string | null =>
+  LEFTHOOK_CONFIGS.map((name) => path.join(top, name)).find((file) => existsSync(file)) ?? null;
+
+// Whether a hook, script or config really runs the helper, not just mentions
+// it. Shell text: a non-comment line invoking it, either directly
+// (`sh …/workit/session-trailer.sh`) or as `sh "$h"` after an `h=` line
+// naming it. Control flow (an `exit` before the line, an `if false`) is out
+// of scope: this reads lines, it does not run them.
+const isComment = (line: string) => /^\s*#/.test(line);
+// `sh` in command position: line start or after `;`, `&`, `|`, `(`, `!`,
+// `then`, `do` or `else` (so `echo sh $h` does not count).
+const COMMAND_SH = String.raw`(?:^|[;&|(!]|\b(?:then|do|else)\s)\s*sh\s+`;
+const DIRECT_CALL = new RegExp(
+  String.raw`${COMMAND_SH}(?:"[^"]*|\S*)${HELPER_REF.replaceAll(".", String.raw`\.`)}`,
+);
+const VAR_CALL = new RegExp(String.raw`${COMMAND_SH}"?\$h\b`);
+const runsHelperText = (text: string): boolean => {
+  const lines = text.split(/\r?\n/).filter((line) => !isComment(line));
+  const assigned = lines.some((line) => /(?:^|[\s;])h=/.test(line) && line.includes(HELPER_REF));
+  return lines.some((line) => DIRECT_CALL.test(line) || (assigned && VAR_CALL.test(line)));
+};
+
+const LEFTHOOK_YAML = [
+  "lefthook.yml",
+  "lefthook.yaml",
+  ".lefthook.yml",
+  ".lefthook.yaml",
+  "lefthook-local.yml",
+  "lefthook-local.yaml",
+  ".lefthook-local.yml",
+  ".lefthook-local.yaml",
+];
+const indentOf = (line: string) => line.length - line.trimStart().length;
+
+/**
+ * A small indentation-aware read of a lefthook YAML config (no YAML library
+ * in deps): a `run:` value under the top-level `prepare-commit-msg:` key, on
+ * a non-comment line (or its `|`/`>` block), that runs the helper.
+ * lefthook.json/.toml are not read, so they never count as manual.
+ */
+const lefthookRunsHelper = (text: string): boolean => {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^prepare-commit-msg:\s*(?:#.*)?$/.test(line));
+  if (start < 0) return false;
+  const block: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (line.trim() && !isComment(line) && indentOf(line) === 0) break;
+    block.push(line);
+  }
+  return block.some((line, i) => {
+    if (isComment(line)) return false;
+    const runKey = /^(\s*)(?:-\s+)?run:\s*(.*)$/.exec(line);
+    if (!runKey) return false;
+    let value = runKey[2] ?? "";
+    if (/^[|>][-+]?\s*$/.test(value)) {
+      const body: string[] = [];
+      for (const next of block.slice(i + 1)) {
+        if (next.trim() && indentOf(next) <= indentOf(line)) break;
+        body.push(next);
+      }
+      value = body.join("\n");
+    }
+    return runsHelperText(value);
+  });
+};
+
+const isExecutable = (file: string): boolean => {
+  if (process.platform === "win32") return true;
+  try {
+    return (statSync(file).mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+};
+
+/** Whether the manual line is really in place for this owner. */
+const manualInPlace = (input: ManualInput, target: string): boolean => {
+  if (input.owner === "lefthook")
+    return LEFTHOOK_YAML.some((name) => {
+      const text = readText(path.join(input.top, name));
+      return text !== null && lefthookRunsHelper(text);
+    });
+  const text = readText(target);
+  if (text === null || !runsHelperText(text)) return false;
+  // husky v9's `h` runs the user script with `sh -e`, so it needs no +x; any
+  // other target is a hook git runs itself, which git skips unless executable.
+  return (input.owner === "husky" && target !== input.hookPath) || isExecutable(target);
+};
+
+/** husky v9 stubs source `h` beside them; v4-v8 hooks source `_/husky.sh`. */
+const isHuskyV9 = (text: string, hooksDir: string): boolean =>
+  /\$\(dirname (?:-- )?"\$0"\)\/h"/.test(text) && existsSync(path.join(hooksDir, "h"));
+
+const ownerOf = (text: string, hooksDir: string, top: string): HookOwner => {
+  if (text.includes("husky.sh") || isHuskyV9(text, hooksDir)) return "husky";
+  if (/lefthook/i.test(text) || lefthookConfig(top)) return "lefthook";
+  return "other";
+};
+
+type ManualInput = {
+  owner: HookOwner;
+  text: string;
+  hooksDir: string;
+  hookPath: string;
+  top: string;
+  /** Workit's earlier hook, moved aside by lefthook. */
+  displaced: string | null;
+};
+
+/** The file the manual line goes in for this owner. */
+const manualTargetOf = ({ owner, text, hooksDir, hookPath, top }: ManualInput): string => {
+  // husky v9 points core.hooksPath at `.husky/_` and runs `.husky/<hook>`
+  // from the stub; husky v4-v8 hooks are the user's files themselves.
+  if (owner === "husky" && isHuskyV9(text, hooksDir))
+    return path.join(path.dirname(hooksDir), SESSION_HOOK_NAME);
+  if (owner === "lefthook") return lefthookConfig(top) ?? path.join(top, "lefthook.yml");
+  return hookPath;
+};
+
+const manualFor = (input: ManualInput): string => {
+  const { owner, displaced } = input;
+  const target = manualTargetOf(input);
+  const stale = displaced ? `; delete the stale ${displaced} (nothing runs it)` : "";
+  if (owner === "husky")
+    return `add this line to ${target} (create it if missing; husky runs it)${stale}: ${manualTrailerLine()}`;
+  if (owner === "lefthook")
+    return [
+      `merge this job into ${target} (add it to an existing \`${SESSION_HOOK_NAME}:\` \`jobs:\` list rather than a second \`${SESSION_HOOK_NAME}:\` key), then run \`lefthook install\`${stale}:`,
+      `${SESSION_HOOK_NAME}:`,
+      "  jobs:",
+      "    - name: workit-session",
+      `      run: ${lefthookTrailerRun()}`,
+    ].join("\n");
+  return `add this line to ${target} (a new file needs \`#!/bin/sh\` as its first line and \`chmod +x\`)${stale}: ${manualTrailerLine()}`;
+};
+
+const leftoverOf = (hooksDir: string): string | undefined => {
+  const chained = path.join(hooksDir, LEGACY_CHAINED);
+  const commitMsg = path.join(hooksDir, "commit-msg");
+  const oldOurs = readText(commitMsg)?.includes(SESSION_HOOK_MARKER) ?? false;
+  if (exists(chained))
+    return oldOurs
+      ? `${chained} was left by an earlier Workit build: move it back to ${commitMsg} (replacing Workit's old hook there)`
+      : `${chained} was left by an earlier Workit build and nothing runs it: if it is your original commit-msg hook, move it back to ${commitMsg}; otherwise delete it`;
+  if (oldOurs)
+    return `${commitMsg} is a hook from an earlier Workit build; delete it (the trailer now comes from ${SESSION_HOOK_NAME})`;
+  return undefined;
+};
+
+/** Where the prepare-commit-msg hook of the repository at `cwd` lives, and what it is. */
+export function inspectSessionHook(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): SessionHookStatus {
+  const none = { hooksDir: null, hookPath: null, helperPath: null, helperCurrent: false };
+  if (!existsSync(cwd)) return { state: "not_git", ...none };
+  const top = run(cwd, ["rev-parse", "--show-toplevel"], env);
+  if (!top.ok || !top.out) return { state: "not_git", ...none };
+  const paths = run(
+    cwd,
+    ["rev-parse", "--path-format=absolute", "--git-common-dir", "--git-path", "hooks"],
+    env,
+  );
+  const [commonDir, hooksDir] = paths.out.split(/\r?\n/);
+  if (!paths.ok || !commonDir || !hooksDir) return { state: "not_git", ...none };
+  const hookPath = path.join(hooksDir, SESSION_HOOK_NAME);
+  const helperPath = path.join(commonDir, ...HELPER);
+  const helperCurrent = readText(helperPath) === SESSION_TRAILER_SCRIPT;
+  const leftover = leftoverOf(hooksDir);
+  const base = { hooksDir, hookPath, helperPath, helperCurrent, ...(leftover ? { leftover } : {}) };
+  const blocked = (reason: string, owner: HookOwner, text = ""): SessionHookStatus => {
+    const old = `${hookPath}.old`;
+    const displaced = readText(old)?.includes(SESSION_HOOK_MARKER) ? old : null;
+    const input = { owner, text, hooksDir, hookPath, top: top.out, displaced };
+    const manualTarget = manualTargetOf(input);
+    const owned = text ? { owner } : {};
+    // The user already added the line where it belongs.
+    if (manualInPlace(input, manualTarget))
+      return {
+        state: "manual",
+        ...base,
+        ...owned,
+        manualTarget,
+        via: owner === "other" ? "existing hook" : owner,
+      };
+    return {
+      state: "blocked",
+      ...base,
+      ...owned,
+      reason: displaced ? `${reason} (Workit's earlier hook was moved to ${old})` : reason,
+      manual: manualFor(input),
+      manualTarget,
+    };
+  };
+  if (!inside(hooksDir, commonDir) && !inside(hooksDir, top.out))
+    return blocked(
+      `core.hooksPath ${hooksDir} is outside the repository; a hook there runs in every repository that uses it`,
+      "other",
+    );
+  const text = exists(hookPath) ? (readText(hookPath) ?? "") : null;
+  if (text !== null) {
+    if (text === SESSION_HOOK_SCRIPT)
+      return { state: helperCurrent ? "installed" : "outdated", ...base };
+    if (text.includes(SESSION_HOOK_MARKER)) return { state: "outdated", ...base };
+    const owner = ownerOf(text, hooksDir, top.out);
+    return blocked(
+      `${hookPath} belongs to ${owner === "other" ? "another hook" : owner}; Workit never replaces it`,
+      owner,
+      text,
+    );
+  }
+  if (!inside(hooksDir, commonDir)) {
+    // A hooks directory in the working tree (a committed .githooks): a new
+    // file there must be ignored, or it shows up in git status.
+    const rel = path.relative(top.out, hookPath).split(path.sep).join("/");
+    if (!run(top.out, ["check-ignore", "-q", "--", rel], env).ok)
+      return blocked(
+        `${hooksDir} is in the working tree and not ignored; the hook would show up as a new file`,
+        "other",
+      );
+  }
+  return { state: "missing", ...base };
+}
+
+/**
+ * Write `content` through a staged file renamed into place. The finally only
+ * matters when the write or chmod throws after the staged file exists; a
+ * rename failure cannot be provoked through inspect (an unreadable or
+ * directory slot is reported blocked first), so that path is not tested.
+ */
+const writeExecutable = (file: string, content: string) => {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const staged = `${file}.workit-new`;
+  try {
+    writeFileSync(staged, content, { mode: 0o755 });
+    chmodSync(staged, 0o755);
+    renameSync(staged, file);
+  } finally {
+    rmSync(staged, { force: true });
+  }
+};
+
+export type SessionHookInstall = {
+  /** What --fix did to the hook slot: wrote the hook, rewrote an older one, or nothing. */
+  action: "installed" | "updated" | "unchanged" | "skipped";
+  /** Whether the helper was (re)written. */
+  helperWritten: boolean;
+  status: SessionHookStatus;
+  detail: string;
+};
+
+/**
+ * Install (or refresh) the helper and the hook for the repository at `cwd`.
+ * The caller decides that `cwd` is a Workit workspace. The helper is written
+ * even when the slot is blocked, so the manual line works; the slot is written
+ * only when empty or holding Workit's own hook.
+ */
+export function installSessionHook(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): SessionHookInstall {
+  const status = inspectSessionHook(cwd, env);
+  if (status.state === "not_git")
+    return {
+      action: "skipped",
+      helperWritten: false,
+      status,
+      detail: "not inside a git work tree",
+    };
+  const helperWritten = !status.helperCurrent;
+  if (helperWritten) writeExecutable(status.helperPath!, SESSION_TRAILER_SCRIPT);
+  const helper = helperWritten ? `; wrote ${status.helperPath}` : "";
+  if (status.state === "installed")
+    return {
+      action: "unchanged",
+      helperWritten,
+      status,
+      detail: `hook already at ${status.hookPath}`,
+    };
+  if (status.state === "manual")
+    return {
+      action: "unchanged",
+      helperWritten,
+      status: inspectSessionHook(cwd, env),
+      detail: `${status.manualTarget} already runs the helper (via ${status.via})${helper}`,
+    };
+  if (status.state === "blocked")
+    return {
+      action: "skipped",
+      helperWritten,
+      status: inspectSessionHook(cwd, env),
+      detail: `${status.reason}${helper}`,
+    };
+  const fresh = status.state === "missing";
+  const slotCurrent = readText(status.hookPath!) === SESSION_HOOK_SCRIPT;
+  if (!slotCurrent) writeExecutable(status.hookPath!, SESSION_HOOK_SCRIPT);
+  const verb = fresh ? "installed" : "updated";
+  return {
+    action: verb,
+    helperWritten,
+    status: inspectSessionHook(cwd, env),
+    detail: `${verb} the Workit ${SESSION_HOOK_NAME} hook at ${status.hookPath}${helper}`,
+  };
+}

package/src/hooks/context.ts

@@ -74,6 +74,13 @@ export const currentTaskEntry = (
  * CLI (`workit_cli`, which creates implicit tasks) are tooling, not
  * conversations.
  */
+/** Whether a host conversation other than `session` is bound to the task. */
+const otherConversation = (entry: TaskIndexEntry, session: SessionHandle): boolean =>
+  entry.sessions.some(
+    (item) =>
+      item.host !== "workit_cli" && !(item.host === session.host && item.handle === session.handle),
+  );
+
 const implicitTaskEntry = (
   store: TaskStore,
   entries: TaskIndexEntry[],
@@ -81,13 +88,7 @@ const implicitTaskEntry = (
 ): TaskIndexEntry | null => {
   const open = entries.filter(
     (entry) =>
-      entry.key !== null &&
-      entry.status !== "closed" &&
-      !entry.sessions.some(
-        (item) =>
-          item.host !== "workit_cli" &&
-          !(item.host === session.host && item.handle === session.handle),
-      ),
+      entry.key !== null && entry.status !== "closed" && !otherConversation(entry, session),
   );
   if (open.length === 0) return null;
   const key = store.currentKey();
@@ -174,23 +175,37 @@ export function sessionCompactContext(
   const entry =
     currentTaskEntry(listed.data, session, selection) ??
     implicitTaskEntry(store, listed.data, session);
-  return entry ? entryCompactContext(store, entry, session, context) : null;
+  return entryCompactContext(store, entry, session, context);
 }
 
 function entryCompactContext(
   store: TaskStore,
-  entry: TaskIndexEntry,
+  entry: TaskIndexEntry | null,
   session: SessionHandle,
   context: OperationContext,
 ): string | null {
+  // The task of the branch this one was cut from: its decisions stay in view
+  // (labelled with their origin) instead of vanishing on a switch. Another
+  // conversation's task is never injected.
+  const found = store.originTaskEntry();
+  const origin =
+    found.ok &&
+    found.data &&
+    found.data.entry.id !== entry?.id &&
+    !otherConversation(found.data.entry, session)
+      ? found.data
+      : null;
+  if (!entry && !origin) return null;
   const workspace = store.readWorkspace();
-  if (!workspace.ok || !workspace.data) return null;
+  if (!workspace.ok || (entry && !workspace.data)) return null;
   const slot = `${store.root}\0${session.host}\0${session.handle}`;
   const key = canonicalJson({
-    task: entry.id,
-    revision: entry.revision,
-    file: entry.file,
-    workspace: workspace.data.revision,
+    task: entry?.id ?? null,
+    revision: entry?.revision ?? null,
+    file: entry?.file ?? null,
+    // The origin task's log signature changes with every write to it.
+    origin: origin && origin.entry.file,
+    workspace: workspace.data?.revision ?? null,
     caller: context.caller,
     workerId: context.workerId ?? null,
     capabilities: context.capabilities,
@@ -205,18 +220,22 @@ function entryCompactContext(
     (hit.signal === null || hit.signal === recentSignal(store.root))
   )
     return hit.value;
-  const task = store.readTask(entry.id);
-  if (!task.ok) return null;
+  const task = entry ? store.readTask(entry.id) : null;
+  if (task && !task.ok) return null;
   const freshness: Freshness = { mode: "signal", current: () => recentSignal(store.root) };
-  const observed = task.data.evidence.some(isObservedCheck);
-  const files = task.data.decisions.flatMap((decision) =>
+  const observed = task?.data.evidence.some(isObservedCheck) ?? false;
+  const files = (task?.data.decisions ?? []).flatMap((decision) =>
     decision.data.binding.contentRefs.flatMap((ref) =>
       ref.kind === "file" ? [path.resolve(store.root, ref.path)] : [],
     ),
   );
   const observedFiles = filesKey(files);
-  const compact = new WorkitCore(store, context).compactContext(entry.id, freshness);
-  if (!compact.ok) return null;
+  const compact = new WorkitCore(store, context).compactContext(
+    entry?.id ?? null,
+    freshness,
+    origin && { origin: origin.origin, taskId: origin.entry.id },
+  );
+  if (!compact.ok || !compact.data) return null;
   cache.delete(slot);
   cache.set(slot, {
     key,
@@ -264,9 +283,12 @@ export const sessionContextText = (
     const entry =
       currentTaskEntry(listed.data, session, descriptor.context.task) ??
       implicitTaskEntry(store, listed.data, session);
-    const text = entry
-      ? entryCompactContext(store, entry, session, hookOperationContext(input, descriptor))
-      : null;
+    const text = entryCompactContext(
+      store,
+      entry,
+      session,
+      hookOperationContext(input, descriptor),
+    );
     if (text) compact = `\n<workit-task-context>${text}</workit-task-context>`;
     if (options.offer) offer = unfinishedTaskOffer(listed.data, session, entry?.id ?? null);
   } catch {