@harborppm/cli 0.51.0 → 0.52.0

package/README.md

@@ -126,6 +126,8 @@ harbor try PROJECT --drop RL-4 --borrow Sam=3
                                             dry dock: the forecast with changes tried
                                             on a copy (--apply makes them, --save keeps
                                             them to show someone; harbor help try)
+harbor why PROJECT|TASK|MILESTONE           what's holding it up: the line of task
+                                            waits that sets its date, slack per link
 harbor hill [--program P]                   where each project is on its hill
 harbor hill PROJECT --at 0-100|top|done     move it: up to 50 is figuring it out,
                                             past 50 is getting it done

package/dist/app.mjs

@@ -3158,16 +3158,16 @@ const TRIALS = 1e3;
 const MAX_WEEKS = 104;
 /** Fewer finished tasks than this and the forecast says it's rough. */
 const ROUGH_BELOW = 5;
-const noon$1 = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
+const noon$2 = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
 /** Tasks finished in each of the last weeks, oldest first. Done tasks without a date, or dated after now, count as finished now. */
 function weeklyFinished(tasks, startDate, now, weeks = 6) {
-	const today = noon$1(todayISO(now));
-	const age = Math.floor(differenceInCalendarDays(today, noon$1(startDate)) / 7) + 1;
+	const today = noon$2(todayISO(now));
+	const age = Math.floor(differenceInCalendarDays(today, noon$2(startDate)) / 7) + 1;
 	const span = Math.max(1, Math.min(weeks, age));
 	const counts = new Array(span).fill(0);
 	for (const t of tasks) {
 		if (t.status !== "done") continue;
-		const at = t.completedAt ? noon$1(t.completedAt) : today;
+		const at = t.completedAt ? noon$2(t.completedAt) : today;
 		const back = Math.max(0, differenceInCalendarDays(today, at));
 		const week = Math.floor(back / 7);
 		if (week < span) counts[span - 1 - week] += 1;
@@ -3273,7 +3273,7 @@ function tideForecast(project, tasks, now, opts = {}) {
 		remaining
 	};
 	const today = todayISO(now);
-	const base = noon$1(today);
+	const base = noon$2(today);
 	const paced = simulate(remaining, weekly, hash(`${project.id}|${remaining}|${today}`), Math.max(0, opts.pace ?? 1));
 	const at = (share, list = runs) => list[Math.min(list.length - 1, Math.ceil(share * list.length) - 1)];
 	let lastDue = null;
@@ -3281,12 +3281,12 @@ function tideForecast(project, tasks, now, opts = {}) {
 		if (t.status === "done" || !t.dueDate) continue;
 		if (!lastDue || t.dueDate > lastDue.dueDate) lastDue = t;
 	}
-	const floor = lastDue ? differenceInCalendarDays(noon$1(lastDue.dueDate), base) : 0;
+	const floor = lastDue ? differenceInCalendarDays(noon$2(lastDue.dueDate), base) : 0;
 	const sounded = soundingFloors(tasks, opts.reflections, base, hash(`${project.id}|sound|${today}`));
 	const runs = paced.map((d, i) => Math.max(d, floor, sounded.floors?.[i] ?? 0)).sort((a, b) => a - b);
 	const heldBy = lastDue && floor > at(.5, paced) ? lastDue : null;
 	const dayOf = (days) => Number.isFinite(days) ? todayISO(addDays(base, days)) : null;
-	const toEnd = differenceInCalendarDays(noon$1(project.endDate), base);
+	const toEnd = differenceInCalendarDays(noon$2(project.endDate), base);
 	const byEnd = runs.filter((d) => d <= toEnd).length / runs.length;
 	const last = Math.max(Number.isFinite(at(.99)) ? at(.99) : 728, toEnd + 14, 7);
 	const curve = [];
@@ -16966,7 +16966,7 @@ function dueFrom(value, now) {
 * The CLI saves through the sync loop afterwards.
 */
 init_fog();
-const plural$2 = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const plural$3 = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 async function sweepFog(opts) {
 	const { store, ask, say, today } = opts;
 	const start = store.getState();
@@ -16982,7 +16982,7 @@ async function sweepFog(opts) {
 		say("No fog: every open task was touched in the last three weeks.");
 		return tally;
 	}
-	say(`Clear the fog · ${plural$2(queue.length, "task")} nobody has opened, moved or commented on for three weeks.`);
+	say(`Clear the fog · ${plural$3(queue.length, "task")} nobody has opened, moved or commented on for three weeks.`);
 	say("k still needed   d new date   x drop it   s skip   q stop\n");
 	let stopped = false;
 	for (let i = 0; i < queue.length && !stopped; i++) {
@@ -18281,9 +18281,9 @@ var commands_exports = /* @__PURE__ */ __exportAll({
 /** The one line a sync ends with; a dry run's says what it would have done. */
 function syncLine(report, dryRun = false) {
 	const parts = [
-		report.sent.length ? `${dryRun ? "would send" : "sent"} ${plural$1(report.sent.length, "change")} to Harbor` : "",
-		report.added.length ? `${dryRun ? "would add" : "added"} ${plural$1(report.added.length, "task")}` : "",
-		report.took.length ? `${dryRun ? "would bring in" : "brought in"} ${plural$1(report.took.length, "change")} from Harbor` : ""
+		report.sent.length ? `${dryRun ? "would send" : "sent"} ${plural$2(report.sent.length, "change")} to Harbor` : "",
+		report.added.length ? `${dryRun ? "would add" : "added"} ${plural$2(report.added.length, "task")}` : "",
+		report.took.length ? `${dryRun ? "would bring in" : "brought in"} ${plural$2(report.took.length, "change")} from Harbor` : ""
 	].filter(Boolean);
 	if (dryRun) return `⚓ Dry run: ${parts.length ? parts.join(", ") : "already in step with Harbor"}. Nothing was written or sent.`;
 	return parts.length ? `⚓ ${parts.join(", ")}.` : "⚓ Already in step with Harbor.";
@@ -18338,13 +18338,13 @@ async function initHere(opts) {
 		dryRun: opts.dryRun
 	});
 	const { project, harbor } = made.config;
-	const counted = made.open === made.tasks ? plural$1(made.tasks, "task") : `${made.open} open and ${made.tasks - made.open} done ${made.tasks === 1 ? "task" : "tasks"}`;
+	const counted = made.open === made.tasks ? plural$2(made.tasks, "task") : `${made.open} open and ${made.tasks - made.open} done ${made.tasks === 1 ? "task" : "tasks"}`;
 	if (opts.dryRun) {
-		opts.say(made.moved ? `Would move this folder's ${plural$1(made.moved, "task")} into ${project.name} (${project.key}) in ${harbor.name}.` : `Would make ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}.`);
+		opts.say(made.moved ? `Would move this folder's ${plural$2(made.moved, "task")} into ${project.name} (${project.key}) in ${harbor.name}.` : `Would make ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}.`);
 		opts.say("Dry run: nothing was written or sent. Run it again without --dry-run to do it.");
 		return made.config;
 	}
-	opts.say(made.moved ? `Moved this folder's ${plural$1(made.moved, "task")} into ${project.name} in ${harbor.name}.` : `Made ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}. Commit it like any code.`);
+	opts.say(made.moved ? `Moved this folder's ${plural$2(made.moved, "task")} into ${project.name} in ${harbor.name}.` : `Made ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}. Commit it like any code.`);
 	opts.say("Edit a file, or add one, then run harbor sync. Changes on the website come back the same way.");
 	if (opts.hook) opts.say(await addHook(home));
 	return made.config;
@@ -18405,12 +18405,12 @@ async function openLocalPlan(dir, say) {
 		}]
 	};
 }
-var plural$1, shownDir, HOOK;
+var plural$2, shownDir, HOOK;
 var init_commands = __esmMin((() => {
 	init_errors();
 	init_folder();
 	init_repo_sync();
-	plural$1 = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+	plural$2 = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 	shownDir = (cwd, dir) => `${relative(cwd, dir) || ".harbor"}/`;
 	HOOK = "harbor sync --quiet || true";
 }));
@@ -21186,7 +21186,7 @@ function bucketFor(state, inst) {
 	return bucket;
 }
 let handoff;
-const open = [];
+const open$1 = [];
 const memo = {
 	alloc(_inst, payload, empty) {
 		const bucket = handoff;
@@ -21197,7 +21197,7 @@ const memo = {
 			issues: null
 		};
 		bucket.set(payload.value, entry);
-		open.push(entry);
+		open$1.push(entry);
 		return empty;
 	},
 	guard(inst) {
@@ -21263,10 +21263,10 @@ const memo = {
 					return payload;
 				}
 				handoff = bucket;
-				const depth = open.length;
+				const depth = open$1.length;
 				const result = base(payload, ctx);
 				handoff = void 0;
-				const entry = open.length > depth ? open.pop() : void 0;
+				const entry = open$1.length > depth ? open$1.pop() : void 0;
 				if (result instanceof Promise) return result.then((r) => {
 					if (entry) entry.issues = r.issues.length ? cloneIssues(r.issues) : NO_ISSUES;
 					return r;
@@ -23638,18 +23638,18 @@ init_format();
 const BURN_DAYS = 56;
 /** A window shorter than a week says too little to read a rate from. */
 const MIN_DAYS = 7;
-const noon = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
+const noon$1 = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
 /**
 * Spend a day over the last BURN_DAYS (or the project's life, when it's
 * younger), from the ledger; null when nothing was spent in that time.
 */
 function burnPerDay(entries, startDate, now) {
-	const today = noon(todayISO(now));
-	const age = differenceInCalendarDays(today, noon(startDate)) + 1;
+	const today = noon$1(todayISO(now));
+	const age = differenceInCalendarDays(today, noon$1(startDate)) + 1;
 	const span = Math.max(MIN_DAYS, Math.min(56, age));
 	let sum = 0;
 	for (const e of entries) {
-		const back = differenceInCalendarDays(today, noon(e.date));
+		const back = differenceInCalendarDays(today, noon$1(e.date));
 		if (back >= 0 && back < span) sum += e.amount;
 	}
 	return sum > 0 ? sum / span : null;
@@ -23666,8 +23666,8 @@ function slipCost(project, tide, entries, now) {
 	const from = project.endDate > today ? project.endDate : today;
 	const point = (date) => {
 		if (!date) return null;
-		const daysLate = Math.max(0, differenceInCalendarDays(noon(date), noon(from)));
-		const ahead = Math.max(0, differenceInCalendarDays(noon(date), noon(today)));
+		const daysLate = Math.max(0, differenceInCalendarDays(noon$1(date), noon$1(from)));
+		const ahead = Math.max(0, differenceInCalendarDays(noon$1(date), noon$1(today)));
 		return {
 			date,
 			daysLate,
@@ -23682,6 +23682,209 @@ function slipCost(project, tide, entries, now) {
 	};
 }
 
+//#endregion
+//#region src/lib/long-pole.ts
+init_date_fns();
+init_blockers();
+init_format();
+init_indexes();
+const noon = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
+const days = (from, to) => differenceInCalendarDays(noon(to), noon(from));
+const later = (a, b) => !a ? b : !b ? a : a >= b ? a : b;
+const open = (t) => t.status !== "done";
+/** True when `a` finishes later than `b`, or as late behind a longer line. */
+const beats = (a, b) => !b || a.finish > b.finish || a.finish === b.finish && a.depth > b.depth;
+/**
+* Soonest finish for open tasks, and how many open links lie behind each
+* (itself included), worked out once per task however many wait on it. A
+* loop is cut where it closes. Undated tasks with nothing dated behind them
+* have no finish.
+*/
+function finishes(all, today) {
+	const memo = /* @__PURE__ */ new Map();
+	const onPath = /* @__PURE__ */ new Set();
+	const walk = (t) => {
+		const known = memo.get(t.id);
+		if (known) return known;
+		onPath.add(t.id);
+		let behind = null;
+		for (const b of blockersIn(t, all)) {
+			if (!open(b) || onPath.has(b.id)) continue;
+			const w = walk(b);
+			if (w.finish && beats(w, behind)) behind = w;
+		}
+		const own = t.dueDate ? later(t.dueDate.slice(0, 10), today) : null;
+		onPath.delete(t.id);
+		const out = {
+			finish: later(own, behind?.finish ?? null),
+			depth: (behind?.depth ?? 0) + 1
+		};
+		memo.set(t.id, out);
+		return out;
+	};
+	return { walk };
+}
+/** The line of open tasks ending at `last`, through the blocker that finishes last at each step. */
+function lineTo(last, all, walk) {
+	const line = [last];
+	const seen = /* @__PURE__ */ new Set([last.id]);
+	let cursor = last;
+	for (;;) {
+		let next = null;
+		let best = null;
+		for (const b of blockersIn(cursor, all)) {
+			if (!open(b) || seen.has(b.id)) continue;
+			const w = walk(b);
+			if (w.finish && beats(w, best)) {
+				best = w;
+				next = b;
+			}
+		}
+		if (!next) break;
+		seen.add(next.id);
+		line.unshift(next);
+		cursor = next;
+	}
+	return line;
+}
+function linksOf(line, walk, target, today) {
+	return line.map((task, i) => {
+		const finish = walk(task).finish;
+		const next = line[i + 1];
+		const against = next ? next.dueDate?.slice(0, 10) ?? null : target;
+		return {
+			task,
+			finish,
+			late: Boolean(task.dueDate && task.dueDate.slice(0, 10) < today),
+			slack: against ? days(finish, against) : null
+		};
+	});
+}
+function chainOf(line, walk, target, today) {
+	const links = linksOf(line, walk, target, today);
+	const finish = links[links.length - 1].finish;
+	return {
+		kind: "chain",
+		links,
+		finish,
+		target,
+		over: target ? days(target, finish) : null
+	};
+}
+/** What sets a project's date: the line behind its open task that finishes last. */
+function projectPole(project, all, now) {
+	const today = todayISO(now);
+	const mine = tasksOf(all, project.id).filter(open);
+	if (mine.length === 0) return {
+		kind: "none",
+		reason: "Nothing is open, so nothing holds it up."
+	};
+	const { walk } = finishes(all, today);
+	let last = null;
+	let best = null;
+	for (const t of mine) {
+		const w = walk(t);
+		if (w.finish && beats(w, best)) {
+			best = w;
+			last = t;
+		}
+	}
+	if (!last) return {
+		kind: "none",
+		reason: "None of its open tasks has a due date, so there's no date to trace."
+	};
+	return chainOf(lineTo(last, all, walk), walk, project.endDate.slice(0, 10), today);
+}
+/** What holds one task up: the line of open tasks it waits on, ending at it. */
+function taskPole(task, all, now) {
+	const today = todayISO(now);
+	if (!open(task)) return {
+		kind: "none",
+		reason: "It's done, so nothing holds it up."
+	};
+	const { walk } = finishes(all, today);
+	if (!walk(task).finish) return {
+		kind: "none",
+		reason: "Neither it nor anything it waits on has a due date, so there's no date to trace."
+	};
+	return chainOf(lineTo(task, all, walk), walk, task.dueDate?.slice(0, 10) ?? null, today);
+}
+/**
+* What holds a milestone up: of the projects it waits on that still have
+* open work, the one finishing last (its end date, or later when its tasks
+* run past it), and that project's own long pole.
+*/
+function milestonePole(milestone, data, now) {
+	if (milestone.done) return {
+		kind: "none",
+		reason: "It's done, so nothing holds it up."
+	};
+	const waited = blockersIn(milestone, data.projects);
+	if (waited.length === 0) return {
+		kind: "none",
+		reason: "It doesn't wait on any project. Link the projects it needs to trace what sets it."
+	};
+	const due = milestone.dueDate.slice(0, 10);
+	const runs = waited.flatMap((project) => {
+		if (project.health === "done" || !tasksOf(data.tasks, project.id).some(open)) return [];
+		const pole = projectPole(project, data.tasks, now);
+		const end = project.endDate.slice(0, 10);
+		return [{
+			project,
+			pole,
+			finish: pole.kind === "chain" ? later(pole.finish, end) ?? end : end
+		}];
+	});
+	if (runs.length === 0) return {
+		kind: "none",
+		reason: "Every project it waits on is finished."
+	};
+	runs.sort((a, b) => b.finish.localeCompare(a.finish));
+	const first = runs[0];
+	const others = runs.slice(1).map((r) => ({
+		project: r.project,
+		finish: r.finish,
+		slack: days(r.finish, due)
+	}));
+	return {
+		kind: "chain",
+		links: first.pole.kind === "chain" ? first.pole.links.map((l, i, all) => i === all.length - 1 ? {
+			...l,
+			slack: days(l.finish, due)
+		} : l) : [],
+		finish: first.finish,
+		target: due,
+		over: days(due, first.finish),
+		via: {
+			project: first.project,
+			finish: first.finish
+		},
+		others
+	};
+}
+const plural$1 = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/** A link's slack in a few words: "4 days spare", "no slack", "3 days late for what's next". */
+function slackText(slack, last = false) {
+	if (slack == null) return last ? "no date to hold" : "next has no due date";
+	if (slack > 0) return `${plural$1(slack, "day")} spare`;
+	if (slack === 0) return "no slack";
+	return last ? `runs ${plural$1(-slack, "day")} over` : `pushes the next ${plural$1(-slack, "day")}`;
+}
+/**
+* The sentence above the line: what sets the date and how it compares with
+* the date being held. `name` turns a task into what to call it (its key).
+*/
+function poleHeadline(pole, name, held) {
+	if (pole.kind !== "chain") return null;
+	const last = pole.links[pole.links.length - 1];
+	const lead = pole.via ? `${pole.via.project.name} finishes ${shortDate(pole.finish)}` : `${last ? name(last.task) : "It"} can finish ${shortDate(pole.finish)}`;
+	const tail = pole.via && last && last.finish < pole.finish ? ` Its tasks can all be done by ${shortDate(last.finish)}; its end date sets it.` : "";
+	if (pole.over == null || !pole.target) return `${lead}.${tail}`;
+	if (pole.over > 0) return `${lead}, ${plural$1(pole.over, "day")} after ${held} (${shortDate(pole.target)}).${tail}`;
+	if (pole.over === 0) return `${lead}, right on ${held}.${tail}`;
+	return `${lead}, ${plural$1(-pole.over, "day")} before ${held}.${tail}`;
+}
+
 //#endregion
 //#region src/lib/csv.ts
 /**
@@ -24959,6 +25162,80 @@ const HARBOR_TOOLS = [
 			};
 		}
 	}),
+	tool({
+		name: "long_pole",
+		title: "What's holding this up",
+		description: "The long pole behind a project, a task or a milestone: of all the task waits behind it, the one line that sets its date, first blocker to last. Each link has its due date, the soonest it can finish (its due date, later when what it waits on finishes after, today at the earliest for late work) and slack: days it can slip before it moves the next link, or the end; negative when it already does. over is how many days the line finishes past the date held (a project's end, a task's or milestone's due date). For a milestone, via is the project it waits on that finishes last, and others are the rest with their slack." + DATA_NOTE,
+		input: object({
+			harbor: harborArg,
+			of: string().min(1).max(200).describe("A project (id, name or key like \"RR\"), a task key (\"RR-42\") or a milestone (id or name).")
+		}),
+		run: (ctx, input) => {
+			const { data } = ctx;
+			const people = byId(data.people);
+			const projects = byId(data.projects);
+			const keyOf = (t) => taskKey(t, projects.get(t.projectId));
+			const name = (t) => keyOf(t) ?? `“${t.title}”`;
+			const answer = (kind, what, pole, held) => {
+				if (pole.kind !== "chain") return {
+					of: {
+						kind,
+						name: what
+					},
+					none: pole.reason
+				};
+				return {
+					of: {
+						kind,
+						name: what
+					},
+					headline: poleHeadline(pole, name, held),
+					finish: pole.finish,
+					held: pole.target,
+					over: pole.over,
+					...pole.via ? { via: {
+						project: pole.via.project.name,
+						finish: pole.via.finish
+					} } : {},
+					chain: pole.links.map((l, i) => ({
+						id: l.task.id,
+						...keyOf(l.task) ? { key: keyOf(l.task) } : {},
+						title: l.task.title,
+						status: l.task.status,
+						assignee: nameOf(people, l.task.assigneeId),
+						due: dayOf(l.task.dueDate),
+						canFinish: l.finish,
+						late: l.late,
+						slack: l.slack,
+						slackText: slackText(l.slack, i === pole.links.length - 1)
+					})),
+					...pole.others ? { others: pole.others.map((o) => ({
+						project: o.project.name,
+						finish: o.finish,
+						slack: o.slack
+					})) } : {}
+				};
+			};
+			const task = data.tasks.find((x) => x.id === input.of.trim()) ?? findByKey(data, input.of);
+			if (task) return answer("task", name(task), taskPole(task, data.tasks, ctx.now), "its due date");
+			let project = null;
+			try {
+				project = findOne(data.projects, input.of, "project");
+			} catch (err) {
+				if (!(err instanceof ToolError) || !/^No project matches/.test(err.message)) throw err;
+				const milestones = data.milestones.filter((m) => !m.done);
+				let milestone;
+				try {
+					milestone = findOne(milestones.length ? milestones : data.milestones, input.of, "milestone");
+				} catch (inner) {
+					if (inner instanceof ToolError && /^No milestone matches/.test(inner.message)) throw new ToolError(`No project, task key or open milestone matches "${input.of.trim()}".`);
+					throw inner;
+				}
+				return answer("milestone", milestone.name, milestonePole(milestone, data, ctx.now), "the milestone");
+			}
+			return answer("project", project.name, projectPole(project, data.tasks, ctx.now), "the end date");
+		}
+	}),
 	tool({
 		name: "shipping_forecast",
 		title: "The harbor forecast",

package/lib/cli.mjs

@@ -37,6 +37,7 @@ import {
   soundingText,
   soundingsText,
   voyageText,
+  whyText,
   handoverText,
   fogText,
   agentWorkText,
@@ -89,6 +90,8 @@ export const HELP = `harbor: Harbor from the terminal
                                               dry dock: the forecast with plan
                                               changes tried on a copy; nothing
                                               changes without --apply
+  harbor why PROJECT|TASK|MILESTONE           what's holding it up: the line of
+                                              task waits that sets its date
   harbor hill [--program P]                   where each project is on its hill
   harbor hill PROJECT --at 0-100|top|done     move it: up to 50 is figuring it
                                               out, past 50 is getting it done
@@ -721,6 +724,20 @@ const DETAIL = {
     "  never marks its own work Done; a person does, on the website or in the",
     "  terminal app.",
   ],
+  why: [
+    "  harbor why PROJECT                     the line of task waits that sets a",
+    "                                         project's date, against its end",
+    "  harbor why TASK                        the waits behind one task (a key",
+    "                                         like RR-42), against its due date",
+    "  harbor why MILESTONE                   the project a milestone waits on",
+    "                                         that finishes last, and its line",
+    "",
+    "  Tasks have due dates, not lengths, so a task can finish on its due date",
+    "  at the soonest, never before what it waits on, and never in the past.",
+    "  Each link's slack is the days it can slip before it moves the next one",
+    "  (or the end); a negative one already does. PROJECT is a name, a key",
+    "  like RR, or an id.",
+  ],
   voyage: [
     "  harbor voyage PROJECT                  reads a Done project's voyage log",
     '  harbor voyage PROJECT "YOUR LINE"      writes: adds or changes your line in it',
@@ -2173,6 +2190,12 @@ export async function run(argv, io = {}) {
         soundingsText(r),
       );
     }
+    case "why": {
+      const { positionals, harbor } = parse(spec());
+      const of = positionals.join(" ").trim();
+      if (!of) throw new HarborError("Say what: a project, a task key like RR-42, or a milestone.");
+      return call("long_pole", { harbor, of }, whyText);
+    }
     case "voyage": {
       const { positionals, harbor } = parse(spec());
       const [project, ...words] = positionals;

package/lib/format.mjs

@@ -487,6 +487,35 @@ export function voyageText(r) {
   );
 }
 
+/** What's holding something up, as long_pole answers it: the headline, then the line of waits, first blocker at the top. */
+export function whyText(r) {
+  const what = r.of.kind === "task" ? r.of.name : `${r.of.name}${r.of.kind === "milestone" ? " (milestone)" : ""}`;
+  if (r.none) return `What's holding up ${what}: ${r.none.replace(/^\w/, (c) => c.toLowerCase())}`;
+  const head = [`What's holding up ${what}`];
+  if (r.headline) head.push(r.headline);
+  const chain = r.chain ?? [];
+  const width = Math.min(12, Math.max(0, ...chain.map((l) => (l.key ?? "").length)));
+  const lines = chain.flatMap((l, i) => {
+    const due = l.due ? (l.late ? `was due ${l.due}` : `due ${l.due}`) : "no due date";
+    const finish = l.canFinish !== l.due ? ` · can finish ${l.canFinish}` : "";
+    const row = [
+      `  ${(l.key ?? "").padEnd(width)}${width ? "  " : ""}${l.title}`,
+      `  ${" ".repeat(width)}${width ? "  " : ""}${l.assignee ?? "nobody yet"} · ${due}${finish} · ${l.slackText}`,
+    ];
+    return i < chain.length - 1 ? [...row, `  ${" ".repeat(width ? Math.floor(width / 2) : 0)}│`] : row;
+  });
+  const via = r.via ? [`It waits longest on ${r.via.project}; inside it:`] : [];
+  const others = (r.others ?? []).length
+    ? [
+        "",
+        `Also waits on ${r.others
+          .map((o) => `${o.project} (finishes ${o.finish}, ${o.slack >= 0 ? `${o.slack} day${o.slack === 1 ? "" : "s"} spare` : `${-o.slack} day${o.slack === -1 ? "" : "s"} over`})`)
+          .join(", ")}.`,
+      ]
+    : [];
+  return [...head, "", ...via, ...lines, ...others].join("\n");
+}
+
 /** A position on a 21-wide track, the top of the hill marked in the middle. */
 function hillTrack(at) {
   const cells = Array.from({ length: 21 }, (_, i) => (i === 10 ? "┼" : "─"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",