SKILL.md- the skill, written out in plain English

npx tsx state/bin/head-screen/ctl.ts set --mode thinking --headline "Working the queue" --detail "Reviewing local state only" --task "head-screen v1" --ttl 60 --source codex
npx tsx state/bin/head-screen/ctl.ts get
npx tsx state/bin/head-screen/ctl.ts reset
npx tsx state/bin/head-screen/audit.ts
state/bin/head-screen/launch.sh
HEAD_SCREEN_ONCE=1 state/bin/head-screen/launch.sh

criteria:
  - name: state_file_valid_and_fresh
    kind: deterministic
    check: "Running 'npx tsx state/bin/head-screen/audit.ts' exits with status code 0 and reports score 1.0."
  - name: server_is_running
    kind: deterministic
    check: "A process named 'server.ts' or 'node' listening on a local port associated with head-screen is running."
  - name: browser_display_present
    kind: deterministic
    check: "A Chrome browser window is open and displaying content from 'state/bin/head-screen/server.ts'."
  - name: no_eval_log_reads
    kind: judge
    check: "The 'state/bin/head-screen/server.ts' process does not access or read from log files related to eval, ensuring it only reads its dedicated state file."

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/head-screen.ts -- Canonical state helpers for the local
 * head-screen display.
 */

import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";

const HERE = dirname(fileURLToPath(import.meta.url));
const LOG_DIR = join(HERE, "..", "log");

export const HEAD_SCREEN_PATH = join(LOG_DIR, "head-screen.json");
export const HEAD_SCREEN_EVENTS_PATH = join(LOG_DIR, "head-screen-events.ndjson");

export const HEAD_SCREEN_MODES = [
  "idle",
  "listening",
  "thinking",
  "working",
  "done",
  "blocked",
  "error",
] as const;

export type HeadScreenMode = (typeof HEAD_SCREEN_MODES)[number];

export type HeadScreenLaneStatus =
  | "idle"
  | "queued"
  | "waiting"
  | "paused"
  | "active"
  | "done"
  | "blocked";

export type HeadScreenLane = {
  id: string;
  title: string;
  status: HeadScreenLaneStatus;
  task: string;
  detail: string;
  members: string[];
  count: number;
};

export type HeadScreenCardTone = "neutral" | "info" | "good" | "warn" | "bad";

export type HeadScreenCard = {
  label: string;
  value: string;
  tone: HeadScreenCardTone;
};

export type HeadScreenState = {
  version: 1 | 2;
  mode: HeadScreenMode;
  headline: string;
  detail: string;
  task: string;
  ttl_seconds: number | null;
  expires_at: string | null;
  source: string;
  updated_at: string;
  // version 2 optional extensions written by bin/head-screen/compose.ts; readers that
  // only need the v1 core can ignore these safely.
  [extra: string]: unknown;
};

type UnknownRecord = Record<string, unknown>;

export function headScreenDir(): string {
  return LOG_DIR;
}

export function isHeadScreenMode(mode: unknown): mode is HeadScreenMode {
  return typeof mode === "string" && (HEAD_SCREEN_MODES as readonly string[]).includes(mode);
}

function cleanText(value: unknown, fallback = ""): string {
  if (typeof value !== "string") return fallback;
  return value.replace(/\r\n/g, "\n").trim();
}

function parseTimestamp(value: unknown, field: string): string {
  if (typeof value !== "string" || !value.trim()) throw new Error(`head-screen: missing ${field}`);
  const parsed = Date.parse(value);
  if (Number.isNaN(parsed)) throw new Error(`head-screen: invalid ${field}`);
  return new Date(parsed).toISOString();
}

function parseTtlSeconds(value: unknown): number | null {
  if (value === undefined || value === null || value === "") return null;
  if (typeof value === "number" && Number.isInteger(value) && value >= 0) return value;
  throw new Error("head-screen: ttl_seconds must be a non-negative integer or null");
}

function computeExpiresAt(updatedAt: string, ttlSeconds: number | null): string | null {
  if (ttlSeconds === null) return null;
  return new Date(Date.parse(updatedAt) + ttlSeconds * 1000).toISOString();
}

function assertKnownMode(mode: unknown): HeadScreenMode {
  if (!isHeadScreenMode(mode)) throw new Error(`head-screen: invalid mode "${String(mode)}"`);
  return mode;
}

function assertShape(raw: unknown): UnknownRecord {
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("head-screen: state is not an object");
  return raw as UnknownRecord;
}

export function defaultHeadScreenState(now = new Date(), source = "head-screen"): HeadScreenState {
  const updated_at = now.toISOString();
  return {
    version: 1,
    mode: "idle",
    headline: "",
    detail: "",
    task: "",
    ttl_seconds: null,
    expires_at: null,
    source,
    updated_at,
  };
}

export function parseHeadScreenState(raw: unknown): HeadScreenState {
  const obj = assertShape(raw);
  const updated_at = parseTimestamp(obj.updated_at, "updated_at");
  const ttl_seconds = parseTtlSeconds(obj.ttl_seconds);
  const expires_at = obj.expires_at === undefined || obj.expires_at === null || obj.expires_at === ""
    ? computeExpiresAt(updated_at, ttl_seconds)
    : parseTimestamp(obj.expires_at, "expires_at");
  const expectedExpires = computeExpiresAt(updated_at, ttl_seconds);
  if (ttl_seconds === null && expires_at !== null) throw new Error("head-screen: expires_at must be null when ttl_seconds is null");
  if (ttl_seconds !== null && expires_at !== expectedExpires) throw new Error("head-screen: expires_at does not match ttl_seconds");
  const versionRaw = obj.version === undefined ? 1 : obj.version;
  const version = (versionRaw === 1 || versionRaw === 2) ? (versionRaw as 1 | 2) : (() => { throw new Error("head-screen: unsupported version"); })();
  const base: HeadScreenState = {
    version,
    mode: assertKnownMode(obj.mode),
    headline: cleanText(obj.headline),
    detail: cleanText(obj.detail),
    task: cleanText(obj.task),
    ttl_seconds,
    expires_at,
    source: cleanText(obj.source, "head-screen") || "head-screen",
    updated_at,
  };
  // Preserve v2 extensions verbatim (lanes, roster, signals, recipes, scene, now, recent, need…).
  if (version === 2) {
    for (const k of Object.keys(obj)) {
      if (!(k in base)) base[k] = obj[k];
    }
  }
  return base;
}

export function validateHeadScreenState(state: HeadScreenState): void {
  if (state.version !== 1 && state.version !== 2) throw new Error("head-screen: unsupported version");
  assertKnownMode(state.mode);
  if (!cleanText(state.source)) throw new Error("head-screen: source is required");
  parseTimestamp(state.updated_at, "updated_at");
  const ttl_seconds = parseTtlSeconds(state.ttl_seconds);
  if (ttl_seconds !== state.ttl_seconds) throw new Error("head-screen: ttl_seconds is invalid");
  const expectedExpires = computeExpiresAt(state.updated_at, ttl_seconds);
  if (expectedExpires !== state.expires_at) throw new Error("head-screen: expires_at mismatch");
}

export function readHeadScreenState(): HeadScreenState {
  if (!existsSync(HEAD_SCREEN_PATH)) {
    const state = defaultHeadScreenState();
    validateHeadScreenState(state);
    return state;
  }
  const raw = readFileSync(HEAD_SCREEN_PATH, "utf8");
  if (!raw.trim()) throw new Error("head-screen: state file is empty");
  const state = parseHeadScreenState(JSON.parse(raw));
  validateHeadScreenState(state);
  return state;
}

export function writeHeadScreenState(next: HeadScreenState, atomic = true): HeadScreenState {
  validateHeadScreenState(next);
  if (!existsSync(LOG_DIR)) mkdirSync(LOG_DIR, { recursive: true });
  const body = JSON.stringify(next, null, 2) + "\n";
  if (atomic) {
    const tmp = `${HEAD_SCREEN_PATH}.${process.pid}.${Date.now()}.tmp`;
    writeFileSync(tmp, body, "utf8");
    renameSync(tmp, HEAD_SCREEN_PATH);
  } else {
    writeFileSync(HEAD_SCREEN_PATH, body, "utf8");
  }
  return next;
}

export function nextHeadScreenState(
  current: HeadScreenState,
  patch: Partial<Pick<HeadScreenState, "mode" | "headline" | "detail" | "task" | "ttl_seconds" | "source">> & {
    updated_at?: string;
  },
): HeadScreenState {
  const updated_at = patch.updated_at ? parseTimestamp(patch.updated_at, "updated_at") : new Date().toISOString();
  const ttl_seconds = patch.ttl_seconds === undefined ? current.ttl_seconds : parseTtlSeconds(patch.ttl_seconds);
  const next: HeadScreenState = {
    version: 1,
    mode: assertKnownMode(patch.mode ?? current.mode),
    headline: cleanText(patch.headline ?? current.headline),
    detail: cleanText(patch.detail ?? current.detail),
    task: cleanText(patch.task ?? current.task),
    ttl_seconds,
    expires_at: computeExpiresAt(updated_at, ttl_seconds),
    source: cleanText(patch.source ?? current.source, "head-screen") || "head-screen",
    updated_at,
  };
  validateHeadScreenState(next);
  return next;
}

export function headScreenFreshness(state: HeadScreenState, now = Date.now()): {
  fresh: boolean;
  age_ms: number;
  remaining_ms: number | null;
  stale_reason: string | null;
} {
  const updatedMs = Date.parse(state.updated_at);
  const age_ms = Number.isNaN(updatedMs) ? 0 : Math.max(0, now - updatedMs);
  if (state.expires_at) {
    const expiresMs = Date.parse(state.expires_at);
    const remaining_ms = Number.isNaN(expiresMs) ? null : expiresMs - now;
    return {
      fresh: remaining_ms === null ? false : remaining_ms >= 0,
      age_ms,
      remaining_ms,
      stale_reason: remaining_ms !== null && remaining_ms < 0 ? "ttl-expired" : null,
    };
  }
  return { fresh: true, age_ms, remaining_ms: null, stale_reason: null };
}

scripts- helper scripts it can run

prose-only skill - 2 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet