@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/nightly-launch.mjs

@@ -0,0 +1,118 @@
+import { spawnSync } from 'node:child_process';
+import {
+  ACADEMY_CLI_PATH,
+  SCHEDULED_CLAUDE_PERMISSION_ARGS,
+  SCHEDULED_CODEX_PERMISSION_ARGS,
+} from './core.mjs';
+import { childExitCode } from './exit-code.mjs';
+import { NIGHTLY_JOB_FLAG } from './nightly.mjs';
+
+// The nightly routine's child launch: its prompt, its permission, its env.
+
+// The skill finds its own pending entries: those no dreams report consumed.
+export function nightlyPrompt(skill) {
+  return [
+    `Use the ${skill} skill to consolidate the observation entries that no dreams report has consumed yet.`,
+    'Update the v3 memory surfaces conservatively, write the dreams report,',
+    'and finish with the dreams report path.',
+  ].join(' ');
+}
+
+// Each permission flag a scheduler may render into a provider launch, with the
+// number of values it takes.
+const PERMISSION_FLAGS = {
+  claude: { '--permission-mode': 1, '--dangerously-skip-permissions': 0 },
+  codex: {
+    '--dangerously-bypass-approvals-and-sandbox': 0,
+    '--ask-for-approval': 1,
+    '-a': 1,
+    '--sandbox': 1,
+    '-s': 1,
+  },
+};
+
+// The structured-output flags a scheduler renders so it can read the
+// provider's own session id (Claude) or thread id (Codex) from stdout as soon
+// as the provider starts; without them a one-shot run prints nothing until it
+// exits, and the scheduler counts it as never started.
+const OUTPUT_FLAGS = {
+  claude: { '--verbose': 0, '--output-format': 1 },
+  codex: { '--json': 0 },
+};
+
+// The flags of the runtime that will launch, as a scheduler wrote them into
+// its provider argv; flags for the other runtime are not carried.
+function carriedArgs(table, runtime, providerArgv) {
+  const flags = table[runtime === 'codex' ? 'codex' : 'claude'];
+  const carried = [];
+  providerArgv.forEach((arg, index) => {
+    const [flag, inline] = arg.split(/=(.*)/s);
+    const takes = flags[flag];
+    const value = inline ?? providerArgv[index + 1];
+    if (takes === 0) carried.push(flag);
+    else if (takes === 1 && value !== undefined) carried.push(flag, value);
+  });
+  return carried;
+}
+
+// A provider job's approved permission replaces the scheduled default, so the
+// model that consolidates runs with what the job's owner approved for it.
+function childPermissionArgs(runtime, providerArgv) {
+  const carried = carriedArgs(PERMISSION_FLAGS, runtime, providerArgv);
+  if (runtime !== 'codex') return carried.length ? carried : SCHEDULED_CLAUDE_PERMISSION_ARGS;
+  if (!carried.length) return SCHEDULED_CODEX_PERMISSION_ARGS;
+  const exec = SCHEDULED_CODEX_PERMISSION_ARGS.indexOf('exec');
+  return [...carried, ...SCHEDULED_CODEX_PERMISSION_ARGS.slice(exec)];
+}
+
+// Codex takes its output flag after `exec`; Claude takes it before `-p`.
+function childProviderArgs(runtime, permissionArgs, outputArgs, prompt) {
+  if (runtime !== 'codex') return [...permissionArgs, ...outputArgs, '-p', prompt];
+  const afterExec = permissionArgs.indexOf('exec') + 1;
+  return [
+    ...permissionArgs.slice(0, afterExec),
+    ...outputArgs,
+    ...permissionArgs.slice(afterExec),
+    prompt,
+  ];
+}
+
+export function launchNightlyChild(dir, name, launch) {
+  const { runtime, skill, providerArgv = [] } = launch;
+  const prompt = nightlyPrompt(skill);
+  const permissionArgs = childPermissionArgs(runtime, providerArgv);
+  const outputArgs = carriedArgs(OUTPUT_FLAGS, runtime, providerArgv);
+  console.log(
+    JSON.stringify({
+      event: 'nightly.launch',
+      params: { agent: name, runtime, skill, permissionArgs, outputArgs },
+    }),
+  );
+  const providerArgs = childProviderArgs(runtime, permissionArgs, outputArgs, prompt);
+  // The child, and the provider it launches, write straight to this process's
+  // stdout descriptor, so each provider line reaches the scheduler the moment
+  // it is written. This process writes nothing while the child runs, so its
+  // own JSON lines never interleave with the provider's.
+  const result = spawnSync(
+    process.execPath,
+    [ACADEMY_CLI_PATH, 'run', name, '--', ...providerArgs],
+    {
+      stdio: 'inherit',
+      cwd: dir,
+      env: nightlyChildEnv(),
+    },
+  );
+  return childExitCode(result);
+}
+
+// The dispatch flag is cleared so the child launches its provider instead of
+// entering the nightly routine again. The scheduler's job id still reaches the
+// child; ACADEMY_NIGHTLY_RUN keeps the run entry from deriving the flag from it.
+export function nightlyChildEnv() {
+  const { [NIGHTLY_JOB_FLAG]: _dispatched, ...inherited } = process.env;
+  return {
+    ...inherited,
+    ACADEMY_SKIP_NIGHTLY_TASK: '1',
+    ACADEMY_NIGHTLY_RUN: '1',
+  };
+}

package/scripts/cli/nightly.mjs

@@ -0,0 +1,228 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { estimateTokens } from '../../hooks/context_metrics.mjs';
+import { sweepBridgeObservations } from '../../hooks/memory_bridge.mjs';
+import { markPendingConsolidation, withPendingMarkerLock } from '../../hooks/memory_store.mjs';
+import { readJsonFile } from './codex.mjs';
+import { printHelmSkip } from './helm-skip.mjs';
+import { KIND_PROFILES, kindOf, surfacesFor } from './core.mjs';
+import { skillTemplateExists } from './skills.mjs';
+
+// The nightly skill owns consolidation: it finds the archive entries recorded
+// after its newest dreams report, consolidates them, and writes the next
+// report. Academy launches it when the pending marker says there was session
+// activity, and records only how the run ended. It never reads the report.
+
+// The section names the skills render into the dreams report. The report's
+// consumed entries are the skill's own checkpoint for the next nightly.
+export const NIGHTLY_REPORT_EVIDENCE = {
+  section: 'Consolidation Evidence',
+  consumed: 'Consumed entries',
+  changed: 'Changed surfaces',
+  noChange: 'No-change reason',
+};
+
+/** Derived from an Owner nightly job's id so `academy run` enters the nightly routine. */
+export const NIGHTLY_JOB_FLAG = 'ACADEMY_NIGHTLY_JOB';
+
+// A pack nightly skill replaces the universal one for its kind.
+export const NIGHTLY_SKILL_BY_KIND = {
+  specialist: 'nightly-consolidation',
+  principal: 'principal-nightly',
+  owner: 'owner-nightly',
+};
+
+// The child's own run renders exactly the profile's skills right before the
+// provider starts, so the skill is present only when the profile lists it and
+// a template for it exists: a missing template would fail mid-render instead.
+export function nightlySkillFor(dir, templatesRoot) {
+  const kind = kindOf(dir);
+  const skill = NIGHTLY_SKILL_BY_KIND[kind];
+  const present =
+    KIND_PROFILES[kind].skills.includes(skill) && skillTemplateExists(kind, skill, templatesRoot);
+  return { kind, skill, present };
+}
+
+/** The scheduled prompt of a provider nightly job; the routine builds its own. */
+export function nightlyRoute(kind) {
+  return `Nightly consolidation: use the ${NIGHTLY_SKILL_BY_KIND[kind]} skill.`;
+}
+
+const NIGHTLY_SWEEP_DAYS = 7;
+
+const recordPath = (dir) => join(dir, 'memory', 'nightly-last.json');
+
+// A one-shot scheduled run's last turn lands after its only Stop, so the
+// nightly sweeps a week back before it reads the marker. Swept input is owed
+// consolidation, so it commits with its marker bump, as every writer's does.
+export function sweepBeforeNightly(dir, name) {
+  let copied = 0;
+  mkdirSync(join(dir, 'memory'), { recursive: true });
+  markPendingConsolidation(join(dir, 'memory'), () => {
+    copied = sweepBridgeObservations(dir, { days: NIGHTLY_SWEEP_DAYS });
+    return copied > 0;
+  });
+  console.log(
+    JSON.stringify({
+      event: 'nightly.sweep',
+      params: { agent: name, days: NIGHTLY_SWEEP_DAYS },
+      result: { copied },
+    }),
+  );
+}
+
+// A Stop hook or note that fired after the revision was read bumped it, and
+// its activity is not covered by this run, so the marker stays (markerKept).
+// The gate mark is taken in the same lock section, before the check.
+export function removeMarkerIfUnchanged(markerPath, revision) {
+  try {
+    return withPendingMarkerLock(dirname(markerPath), () => {
+      const finishedAt = new Date();
+      if (!existsSync(markerPath)) return { finishedAt, markerKept: false };
+      const markerKept = Number(readJsonFile(markerPath, {}).revision) !== revision;
+      if (!markerKept) unlinkSync(markerPath);
+      return { finishedAt, markerKept };
+    });
+  } catch (error) {
+    if (error.code !== 'lock_timeout') throw error;
+    // A live writer holds the lock and may be mid-section, so the marker stays (fail open).
+    console.error(JSON.stringify({ event: 'nightly.marker_lock_timeout', params: { markerPath } }));
+    return { finishedAt: new Date(), markerKept: true };
+  }
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const CLEAN_STATUSES = new Set(['pass', 'skipped_no_input']);
+const NOTE_STAMP_RE = /^- (\d{4}-\d\d-\d\d \d\d:\d\d)/gm;
+
+// Whether a nightly has anything to consolidate: input newer than the last
+// clean record, notes over their cap, or a note stamp a week old. Any doubt
+// (no clean record, a kept marker, a read error) answers true, so a night is
+// never lost. A record without markerKept predates it, so it counts as kept.
+//
+// No input is lost, by construction. A writer appends and bumps the marker in
+// one lock section (markPendingConsolidation's `write`), and on a lock timeout
+// it writes nothing. Against a pass: a writer done before the revision read is
+// in what the child read; one that bumps before the remover's check keeps the
+// marker, and the record's markerKept launches; one after that lock section is
+// newer than the mark taken inside it. Against a skip: its mark comes before
+// these reads, so an append they miss is newer than the mark, and a bump
+// before its remover's check keeps the marker, which markerKept launches.
+function nightlyHasWork(dir) {
+  try {
+    const last = readJsonFile(recordPath(dir), null);
+    const since = Date.parse(last?.finishedAt);
+    if (!CLEAN_STATUSES.has(last?.status) || last.markerKept !== false) return true;
+    if (Number.isNaN(since)) return true;
+    const notes = surfacesFor(dir).find((entry) => entry.name === 'notes');
+    const text = readFileSync(notes.path, 'utf8');
+    if (estimateTokens(text) > notes.cap || hasStaleStamp(text)) return true;
+    return [notes.path, ...observationFiles(dir)].some((path) => statSync(path).mtimeMs > since);
+  } catch {
+    return true;
+  }
+}
+
+function hasStaleStamp(text) {
+  const weekAgo = Date.now() - 7 * DAY_MS;
+  return [...text.matchAll(NOTE_STAMP_RE)].some(
+    ([, stamp]) => new Date(stamp.replace(' ', 'T')).getTime() < weekAgo,
+  );
+}
+
+function observationFiles(dir) {
+  const observations = join(dir, 'memory', 'observations');
+  if (!existsSync(observations)) return [];
+  return readdirSync(observations)
+    .filter((file) => file.endsWith('.jsonl'))
+    .map((file) => join(observations, file));
+}
+
+// No marker means no input was consumed, so the gate mark stays: a note whose
+// marker bump lands after this check must still be newer than the record.
+export function skipNightlyWithoutMarker(attempt) {
+  console.log(
+    `Skipping nightly consolidation for ${attempt.name}: no new session activity since the last run.`,
+  );
+  recordNightlyOutcome(attempt, {
+    status: 'skipped_no_input',
+    reason: 'no_pending_marker',
+    keepMark: true,
+  });
+  printHelmSkip('no_pending_input', attempt.name);
+}
+
+// True when it skipped: the run is recorded and the marker it covered removed.
+export function skipNightlyWithoutWork(attempt, markerPath, revision) {
+  // The record ends when the check began, so input that lands during it is newer.
+  const checkedAt = new Date();
+  if (nightlyHasWork(attempt.dir)) return false;
+  console.log(`Skipping nightly consolidation for ${attempt.name}: nothing new to consolidate.`);
+  // Reconciled before the record, so the record says whether the marker stayed.
+  const { markerKept } = removeMarkerIfUnchanged(markerPath, revision);
+  recordNightlyOutcome(attempt, {
+    status: 'skipped_no_input',
+    reason: 'nothing_to_do',
+    finishedAt: checkedAt,
+    markerKept,
+  });
+  printHelmSkip('nothing_to_do', attempt.name);
+  return true;
+}
+
+/** Nightly statuses doctor flags for the operator. */
+export const FLAGGED_NIGHTLY_STATUSES = new Set(['failed', 'missing']);
+
+// What doctor reports for one agent: how its last nightly ended, or `missing`
+// when activity is pending and no nightly has ever run. Null means neither.
+export function nightlyStatus(dir) {
+  const last = readJsonFile(recordPath(dir), null);
+  if (last?.status) {
+    // A no-marker skip keeps an older finishedAt, so the later time is its end.
+    const at = [last.startedAt, last.finishedAt].filter(Boolean).sort().at(-1) ?? null;
+    return { status: last.status, at, reason: last.reason ?? null };
+  }
+  if (!existsSync(join(dir, 'memory', 'pending-consolidation.json'))) return null;
+  return { status: 'missing', at: null, reason: 'pending_without_receipt' };
+}
+
+// One record and one outcome line per attempt: how it ended, nothing it judged.
+// The gate's mark is finishedAt plus markerKept; `keepMark` carries the
+// previous record's. markerKept defaults to true: only a pass or skip whose
+// revision held shows the record covers the pending marker.
+export function recordNightlyOutcome(attempt, outcome) {
+  const finishedAt = outcome.finishedAt ?? new Date();
+  const path = recordPath(attempt.dir);
+  const previous = outcome.keepMark ? readJsonFile(path, null) : null;
+  const last = {
+    status: outcome.status,
+    startedAt: attempt.startedAt.toISOString(),
+    finishedAt: outcome.keepMark ? (previous?.finishedAt ?? null) : finishedAt.toISOString(),
+    markerKept: outcome.keepMark ? previous?.markerKept !== false : (outcome.markerKept ?? true),
+    provider: attempt.provider,
+    exitCode: outcome.exitCode ?? null,
+    reason: outcome.reason,
+    memory: attempt.memory ?? null,
+  };
+  mkdirSync(join(attempt.dir, 'memory'), { recursive: true });
+  const tempPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(last, null, 2) + '\n');
+  renameSync(tempPath, path);
+  console.log(
+    JSON.stringify({
+      event: 'nightly.outcome',
+      params: { agent: attempt.name, status: outcome.status, reason: outcome.reason },
+      result: { exitCode: last.exitCode, markerKept: last.markerKept },
+      latencyMs: finishedAt.getTime() - attempt.startedAt.getTime(),
+    }),
+  );
+}

package/scripts/cli/notes.mjs

@@ -1,6 +1,7 @@
-import { appendFileSync, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { AGENTS_ROOT, CLI_NAME, agentDir, isInside, validateName } from './core.mjs';
+import { markPendingConsolidation } from '../../hooks/memory_store.mjs';
+import { ACADEMY_HOME, AGENTS_ROOT, CLI_NAME, agentDir, isInside, validateName } from './core.mjs';
 import { ownershipFault } from './lifecycle.mjs';
 
 // `notes` is not a published contract command, so it has no envelope to answer
@@ -30,7 +31,7 @@ function containedAgentDir(candidate) {
     return dir;
   }
   const fault = ownershipFault(basename(real), real);
-  if (fault) notesFault('not_academy_owned', `${fault} at ${real}`);
+  if (fault) notesFault('not_academy_owned', `${real}: ${fault}`);
   return real;
 }
 
@@ -66,16 +67,65 @@ function localNoteStamp(d = new Date()) {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 }
 
-export function notesAdd(name, text) {
-  if (!text || !text.trim()) {
+// Every line terminator and vertical whitespace a Markdown reader may split on:
+// LF, CR, VT, FF, NEL, U+2028 and U+2029, with the blanks around them.
+const LINE_BREAKS = /[ \t]*[\n\r\v\f\u0085\u2028\u2029]+\s*/g;
+
+function toOneLine(text) {
+  return text.replace(LINE_BREAKS, ' ').trim();
+}
+
+function endsMidLine(path) {
+  if (!existsSync(path)) return false;
+  const text = readFileSync(path, 'utf8');
+  return text.length > 0 && !text.endsWith('\n');
+}
+
+// A proposal about the user lands at the end of the shared user.md, tagged
+// `[proposed]` and with the agent that wrote it. One line, so the text cannot
+// open a line of its own.
+function userProposalAdd(dir, text) {
+  const agent = basename(dir);
+  const line = `- [proposed] ${localNoteStamp()} ${agent}: ${toOneLine(text)}\n`;
+  const userPath = join(ACADEMY_HOME, 'user.md');
+  mkdirSync(ACADEMY_HOME, { recursive: true });
+  appendFileSync(userPath, `${endsMidLine(userPath) ? '\n' : ''}${line}`);
+  console.log(
+    JSON.stringify({
+      event: 'notes.user_proposed',
+      params: { agent },
+      result: { path: userPath },
+    }),
+  );
+  console.log(`Proposed → ${userPath}`);
+}
+
+export function notesAdd(name, text, { user = false } = {}) {
+  // Judge emptiness after the line-break collapse: trim() alone keeps NEL.
+  if (!text || !toOneLine(text)) {
     console.error('Error: note text required.');
-    console.error(`Usage: ${CLI_NAME} notes add [<agent>] "text"`);
+    console.error(`Usage: ${CLI_NAME} notes add [<agent>] [--user] "text"`);
     process.exit(1);
   }
   const dir = ensureAgentHome(resolveNotesAgentDir(name));
+  if (user) {
+    userProposalAdd(dir, text);
+    return;
+  }
   const notesPath = join(dir, 'notes.md');
-  // Append-only: never read or rewrite the whole file (spec §Behavior).
-  appendFileSync(notesPath, `- ${localNoteStamp()}: ${text}\n`);
+  // An agent made before memory/ existed has no directory to hold the marker.
+  const memoryDir = join(dir, 'memory');
+  mkdirSync(memoryDir, { recursive: true });
+  // The note commits with the marker bump that arms tldr's file_exists gate,
+  // so the nightly curator picks it up. Append-only: never read or rewrite
+  // the whole file (spec §Behavior).
+  const noted = markPendingConsolidation(memoryDir, () =>
+    appendFileSync(notesPath, `- ${localNoteStamp()}: ${text}\n`),
+  );
+  if (!noted) {
+    console.error('Error: the memory lock is busy, so the note was not saved. Try again.');
+    process.exit(1);
+  }
   console.log(`Noted → ${notesPath}`);
 }
 

package/scripts/cli/owner-config.mjs

@@ -0,0 +1,181 @@
+import { readAgentYaml } from './yaml.mjs';
+
+// An Owner's working terms live as top-level agent.yaml scalars. A missing
+// scalar reads as the conservative default: business hours, both approval
+// gates, and no merge right. `create --kind owner` writes these same defaults.
+
+const systemTimezone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+
+function ownerDefaults() {
+  return {
+    owner_hours: 'weekdays 09:00-17:00',
+    owner_timezone: systemTimezone(),
+    owner_heartbeat: '30m',
+    owner_gates: 'proposal, pr',
+    owner_may_merge: 'false',
+    owner_contact: 'email',
+  };
+}
+
+// The docs example carries inline comments after quoted values; the shared
+// reader keeps both, so strip the comment and then the quotes it left inside.
+function cleanScalar(value) {
+  return value
+    .replace(/\s+#.*$/, '')
+    .trim()
+    .replace(/^["']|["']$/g, '');
+}
+
+export function ownerConfig(dir) {
+  const yaml = readAgentYaml(dir);
+  const config = ownerDefaults();
+  for (const key of Object.keys(config)) {
+    const value = yaml[key] === undefined ? '' : cleanScalar(yaml[key]);
+    if (value) config[key] = value;
+  }
+  return config;
+}
+
+const OWNER_HOURS_WINDOW = /^(daily|weekdays)\s+(\d{2}):(\d{2})-(\d{2}):(\d{2})$/;
+
+const toMinutes = (hours, minutes) => Number(hours) * 60 + Number(minutes);
+
+// The one reader of owner_hours: the daily job's opening time and the heartbeat
+// cron window both come from this parse, so a form that registers a daily job
+// also registers a heartbeat. Forms: "24x7", or
+// "daily|weekdays HH:MM-HH:MM". The start is inside the window, the end is not;
+// "24:00" is a valid end; an end before the start runs past midnight. Anything
+// else is null, and each caller decides what that means.
+function parseOwnerHours(text) {
+  const hours = text.trim().toLowerCase();
+  if (hours === '24x7') return { always: true };
+  const match = OWNER_HOURS_WINDOW.exec(hours);
+  if (!match) return null;
+  const [, days, startH, startM, endH, endM] = match;
+  const start = toMinutes(startH, startM);
+  const end = toMinutes(endH, endM);
+  const valid = Number(startM) < 60 && Number(endM) < 60 && start < 24 * 60 && end <= 24 * 60;
+  if (!valid || start === end) return null;
+  return { weekdaysOnly: days === 'weekdays', start, end };
+}
+
+// "24x7" has no opening time, so its daily open uses the hour the daily work
+// session has always started at.
+const ALWAYS_OPEN_CRON = '0 6 * * *';
+
+// The daily open fires at the start of the owner_hours window, on the window's
+// days. Null when the window is not one Academy reads, so the caller can say so
+// instead of scheduling a guess.
+export function ownerDailyCron(hours) {
+  const window = parseOwnerHours(hours);
+  if (!window) return null;
+  if (window.always) return ALWAYS_OPEN_CRON;
+  const days = window.weekdaysOnly ? '1-5' : '*';
+  return `${window.start % 60} ${Math.floor(window.start / 60)} * * ${days}`;
+}
+
+const INTERVAL = /^(\d+)(m|h)$/;
+// A stepped field stays a range: cron reads a stepped single value `9/2` as
+// 9 through 23, outside the window.
+const span = (from, to, step) => (from === to && !step ? `${from}` : `${from}-${to}${step}`);
+
+// The hours a heartbeat may fire in, rounded inward to whole hours so no beat
+// lands outside the window. An overnight window is two spans on the calendar
+// day cron reads. Null when no whole hour fits.
+function heartbeatHourSpans({ start, end }) {
+  const first = Math.ceil(start / 60);
+  const stop = Math.floor(end / 60);
+  if (start < end) return first < stop ? [[first, stop - 1]] : null;
+  const spans = [];
+  if (first <= 23) spans.push([first, 23]);
+  if (stop > 0) spans.push([0, stop - 1]);
+  return spans.length ? spans : null;
+}
+
+// The cron minute field and hour step for owner_heartbeat. Intervals that
+// divide an hour fire every N minutes; whole hours that divide a day fire
+// every N hours. Each beat is offset by half the interval, so the first one
+// does not fire at the same minute as the daily open. Null for anything else.
+function heartbeatCadence(every) {
+  const interval = INTERVAL.exec((every ?? '').trim().toLowerCase());
+  if (!interval) return null;
+  const minutes = Number(interval[1]) * (interval[2] === 'h' ? 60 : 1);
+  if (minutes > 0 && minutes < 60 && 60 % minutes === 0) {
+    return { minute: `${Math.floor(minutes / 2)}-59/${minutes}`, step: '' };
+  }
+  const hours = minutes / 60;
+  if (!Number.isInteger(hours) || hours < 1 || 24 % hours !== 0) return null;
+  return { minute: '30', step: hours > 1 ? `/${hours}` : '' };
+}
+
+// One cron line for the heartbeat: tldr then keeps it inside owner_hours in
+// owner_timezone, and `academy run` needs no hours guard. Null when the window
+// or the interval is one cron cannot hold.
+export function ownerHeartbeatCron(hours, every) {
+  const window = parseOwnerHours(hours ?? '');
+  const cadence = heartbeatCadence(every);
+  if (!window || !cadence) return null;
+  const { minute, step } = cadence;
+  if (window.always) return `${minute} *${step} * * *`;
+  const spans = heartbeatHourSpans(window);
+  if (!spans) return null;
+  const hourField = spans.map(([from, to]) => span(from, to, step)).join(',');
+  return `${minute} ${hourField} * * ${window.weekdaysOnly ? '1-5' : '*'}`;
+}
+
+function ownerGateList(gates) {
+  return gates
+    .split(/[\s,]+/)
+    .map((gate) => gate.toLowerCase())
+    .filter((gate) => gate && gate !== 'none');
+}
+
+const GATE_RULES = {
+  proposal:
+    '- `proposal` gate: before you start a new initiative (a Beads epic under a Workstream), write the ' +
+    'rationale and its link to your mandate and strategy, run ' +
+    '`bd gate create --type=human --blocks <epic-id> --json`, send the request, and stop work on that ' +
+    'initiative. Wait until the user resolves the gate. Tasks inside an approved initiative need no gate.',
+  pr:
+    '- `pr` gate: open the PR, block the item with ' +
+    '`bd gate create --type=gh:pr --await-id=<PR URL> --blocks <id> --json`, and stop. ' +
+    'Do not merge it; the gate closes when the user merges it.',
+};
+
+const gateRule = (gate) =>
+  GATE_RULES[gate] ??
+  `- \`${gate}\` gate: stop at this boundary and ask the user. Do not pass it yourself.`;
+
+// The rules this config grants, rendered as plain lines so a run never has to
+// work out its own authority from the raw scalars.
+function ownerAuthority({ owner_gates, owner_may_merge }) {
+  const gates = ownerGateList(owner_gates);
+  const lines = gates.map(gateRule);
+  if (gates.length === 0)
+    lines.push('- No gates: act without asking, inside the mandate in mandate.md.');
+  if (gates.includes('pr')) return lines.join('\n');
+  lines.push(
+    owner_may_merge === 'true'
+      ? '- Merge: merge your own PR only after your merge bar passes. Record its evidence first.'
+      : '- Merge: never merge. Open the PR and report it.',
+  );
+  return lines.join('\n');
+}
+
+export function ownerSkillValues(dir) {
+  const config = ownerConfig(dir);
+  return { ...config, owner_authority: ownerAuthority(config) };
+}
+
+export function ownerYamlBlock() {
+  const defaults = ownerDefaults();
+  return `# Owner terms — work hours and timezone, heartbeat interval, approval gates
+# (proposal, pr, or none), merge right, and how to reach the user.
+owner_hours: "${defaults.owner_hours}"
+owner_timezone: ${defaults.owner_timezone}
+owner_heartbeat: ${defaults.owner_heartbeat}
+owner_gates: ${defaults.owner_gates}
+owner_may_merge: ${defaults.owner_may_merge}
+owner_contact: ${defaults.owner_contact}
+`;
+}