elanous 0.2.32 → 0.2.35

package/src/skills/tools/agent.ts

@@ -60,8 +60,8 @@ export const AGENT_TOOL_DEFAULT_MAX_TURNS = 20;
 export const AGENT_TOOL_TURNS_CEILING = 50;
 
 /** Numeric ceiling on concurrent `run_in_background` Agent-tool fan-out.
- *  Pure declaration — enforcement in dispatchAgent is the follow-up cell
- *  TUI-AGENT-CAPS-WIRING (not wired here). */
+ *  Enforced at exactly one point in `dispatchAgent` (see the
+ *  `background-fanout-limit` block: after dedup, before `noteSeen`). */
 export const AGENT_TOOL_BACKGROUND_FANOUT_CEILING = 8;
 
 /** Clamp a caller-supplied `max_turns` onto `[1, AGENT_TOOL_TURNS_CEILING]`.
@@ -82,7 +82,9 @@ export function stripAgentToolForOneLevelNesting<T extends { name: string }>(
 }
 
 /** Live `run_in_background` tasks occupy fan-out slots until they terminal.
- *  Pure judgement — the ceiling check that uses it is TUI-AGENT-CAPS-WIRING. */
+ *  Counts a task list (e.g. `globalAgentRegistry.list()`). `dispatchAgent`
+ *  enforces the per-session ceiling over its own reservation ledger
+ *  (`backgroundFanoutSlots`) instead — see that field's doc. */
 export function countLiveBackgroundFanout(
   tasks: ReadonlyArray<{ background?: boolean; state?: string }>,
 ): number {
@@ -95,6 +97,35 @@ export function countLiveBackgroundFanout(
   return n;
 }
 
+/** Fallback fan-out session key for dispatches that carry no
+ *  `sessionCache` (agent-cli, one-off callers). All of their slots share
+ *  one process-wide bucket so the ceiling still binds for them. */
+const UNSCOPED_BACKGROUND_FANOUT_SESSION: object = Object.freeze({});
+
+/** Fan-out slots by session (the dispatching session's `SessionCache`
+ *  identity; WeakMap so a dropped session releases its key together with
+ *  the cache instance). A slot is RESERVED in the same synchronous block
+ *  as the ceiling check inside `dispatchAgent` — concurrent dispatches
+ *  that interleave at the async definition-resolution awaits cannot all
+ *  pass the check before any of them registers — and RELEASED when the
+ *  registered task reaches a terminal state (done/error/aborted) via
+ *  `globalAgentRegistry.onTaskDone`. A dispatch that throws before it
+ *  registers releases its own reservation (see
+ *  `releaseReservedFanoutSlot` inside `dispatchAgent`). */
+const backgroundFanoutSlots = new WeakMap<object, number>();
+
+/** Count this session's live fan-out slots (reserved or running). */
+export function countSessionBackgroundFanout(session: object): number {
+  return backgroundFanoutSlots.get(session) ?? 0;
+}
+
+/** Release one of this session's fan-out slots (floors at zero). */
+function releaseBackgroundFanoutSlot(session: object): void {
+  const live = backgroundFanoutSlots.get(session);
+  if (live === undefined || live <= 1) backgroundFanoutSlots.delete(session);
+  else backgroundFanoutSlots.set(session, live - 1);
+}
+
 /** Fallback agent when subagent_type is missing or unresolvable. The
  *  loader picks this up from src/agents/general-purpose.md — built
  *  inline below as a defensive default in case that file is removed. */
@@ -374,19 +405,22 @@ export async function dispatchAgent(
   // burn another turn on the same work. Return a stub that points
   // the parent back to its existing history. Parents stuck in a
   // "keep re-spawning Data Collector" loop escape via this gate.
-  if (opts.sessionCache) {
-    const key = agentCacheKey(requestedType, requestedType, prompt);
+  const sessionCache = opts.sessionCache;
+  const cacheKey = sessionCache
+    ? agentCacheKey(requestedType, requestedType, prompt)
+    : undefined;
+  if (sessionCache && cacheKey) {
     // Key strategy: description is noisy (parents sometimes vary the
     // label between calls); we hash the FUNCTIONAL signature only
     // — subagent_type + prompt. Same prompt to same agent = same
     // expected work, regardless of how the call was labelled.
-    const hit = opts.sessionCache.check(key);
+    const hit = sessionCache.check(cacheKey);
     if (hit) {
       const label = `Agent[${requestedType}] "${description.slice(0, 60)}"`;
       logDedupHit('agent.dedup', label, hit, {
         requestedType,
         description: description.slice(0, 80),
-        consecutive: opts.sessionCache.consecutiveHits,
+        consecutive: sessionCache.consecutiveHits,
       });
 
       // Runtime-level block: same treatment as Read. When the parent
@@ -395,16 +429,16 @@ export async function dispatchAgent(
       // tool_result carries is_error=true. Soft stubs have been
       // observed to produce 6+ retries in the wild; an error break
       // the reflex loop more reliably.
-      if (opts.sessionCache.consecutiveHits >= CONSECUTIVE_DEDUP_BLOCK_THRESHOLD) {
+      if (sessionCache.consecutiveHits >= CONSECUTIVE_DEDUP_BLOCK_THRESHOLD) {
         debug.log('agent.dedup', 'consecutive-block', {
           requestedType,
           description: description.slice(0, 80),
-          consecutive: opts.sessionCache.consecutiveHits,
+          consecutive: sessionCache.consecutiveHits,
           threshold: CONSECUTIVE_DEDUP_BLOCK_THRESHOLD,
         });
         throw new Error(
           `RUNTIME BLOCKED — Agent[${requestedType}] "${description.slice(0, 60)}" ` +
-          `has been spawned ${opts.sessionCache.consecutiveHits} times in a row with ` +
+          `has been spawned ${sessionCache.consecutiveHits} times in a row with ` +
           `no intervening progress. The previous sub-agent's final message is in ` +
           `your conversation history above — use that. Spawn an Agent with a ` +
           `DIFFERENT persona (different subagent_type or a substantively different ` +
@@ -420,9 +454,9 @@ export async function dispatchAgent(
       // ~500 chars of history noise per hit. We now emit the debug
       // event past threshold for traceability but return the normal
       // "spawn a different persona" stub — same message every hit.
-      if (opts.sessionCache.totalHits >= DEDUP_CASCADE_HALT_THRESHOLD) {
+      if (sessionCache.totalHits >= DEDUP_CASCADE_HALT_THRESHOLD) {
         debug.log('agent.dedup', 'cascade-threshold', {
-          totalHits: opts.sessionCache.totalHits,
+          totalHits: sessionCache.totalHits,
           threshold: DEDUP_CASCADE_HALT_THRESHOLD,
           requestedType,
           description: description.slice(0, 80),
@@ -444,7 +478,79 @@ export async function dispatchAgent(
         taskId: 'dedup',
       };
     }
-    opts.sessionCache.noteSeen(key, `Agent[${requestedType}] ${description.slice(0, 60)}`);
+  }
+
+  // ── TUI-AGENT-CAPS-FU: background fan-out ceiling ──
+  //
+  // The ONE enforcement point for AGENT_TOOL_BACKGROUND_FANOUT_CEILING, and
+  // it sits exactly between the dedup short-circuit above and `noteSeen`
+  // below on purpose:
+  //   • after dedup — a repeat of an already-answered prompt still gets the
+  //     dedup stub instead of a fan-out refusal (it never reaches here);
+  //   • before `noteSeen` — a refused launch must NOT register its cache
+  //     key. Otherwise the caller's retry (same prompt, once a slot opens)
+  //     would be answered with "you already got this result" even though no
+  //     child ever ran, permanently poisoning the cache with a spawn that
+  //     never happened.
+  //
+  // Live slots are counted over the shared task ledger: `background` tasks
+  // that have not reached a terminal state (done / error / aborted). So a
+  // slot re-opens the moment any background agent finishes, which is what
+  // lets the next launch through again.
+  let fanoutSession: object | undefined;
+  if (runInBackground) {
+    // Per-session scope: slots count against THIS session's cache
+    // identity (shared fallback bucket for cache-less callers), so a
+    // busy OTHER session cannot starve this one's first launch.
+    fanoutSession = opts.sessionCache ?? UNSCOPED_BACKGROUND_FANOUT_SESSION;
+    const liveBackground = countSessionBackgroundFanout(fanoutSession);
+    if (liveBackground >= AGENT_TOOL_BACKGROUND_FANOUT_CEILING) {
+      debug.log('agent.spawn', 'background-fanout-limit', {
+        cid: debugCorrelationId,
+        requestedType,
+        description: description.slice(0, 80),
+        liveBackground,
+        ceiling: AGENT_TOOL_BACKGROUND_FANOUT_CEILING,
+      }, { level: 'warn' });
+      // Not spawned: no registry task, no provider call, no cache entry.
+      // taskId is a sentinel (like 'dedup' above) so a caller can tell a
+      // refusal from a real spawn without parsing the prose.
+      return {
+        output:
+          `NOT SPAWNED — ${liveBackground} background agents are already live and the ` +
+          `fan-out ceiling is ${AGENT_TOOL_BACKGROUND_FANOUT_CEILING}. A slot reopens as ` +
+          `soon as one of them reaches a terminal state (done/error/aborted); its result ` +
+          `then arrives as a task-notification. Either wait for one to finish, fold this ` +
+          `work into an existing background spawn, or re-issue it without ` +
+          `run_in_background so it runs in the foreground.`,
+        agent: requestedType,
+        cid: debugCorrelationId,
+        durationMs: 0,
+        maxTurns: requestedMaxTurns,
+        taskId: 'background-fanout-limit',
+      };
+    }
+  }
+
+  if (fanoutSession !== undefined) {
+    // Atomic reservation: taken in the SAME synchronous block as the
+    // ceiling check above, before any await — concurrent dispatches
+    // cannot all pass the check and push this session past the ceiling
+    // while their definitions resolve. Released when the registered
+    // task terminals (see the onTaskDone subscription at spawn); a
+    // dispatch that throws before registering releases it in the finally
+    // below, including failures from definition resolution and lazy imports.
+    backgroundFanoutSlots.set(fanoutSession, countSessionBackgroundFanout(fanoutSession) + 1);
+  }
+  const releaseReservedFanoutSlot = (): void => {
+    if (fanoutSession === undefined) return;
+    releaseBackgroundFanoutSlot(fanoutSession);
+    fanoutSession = undefined;
+  };
+
+  try {
+  if (sessionCache && cacheKey) {
+    sessionCache.noteSeen(cacheKey, `Agent[${requestedType}] ${description.slice(0, 60)}`);
   }
 
   // Resolve the agent definition. Try the 4-layer resolver first;
@@ -536,7 +642,9 @@ export async function dispatchAgent(
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      if (!message.includes('is not inside a git repo')) throw error;
+      if (!message.includes('is not inside a git repo')) {
+        throw error;
+      }
       childCwd = opts.cwd ?? getSessionCwd();
       appliedIsolation = 'cwd';
       debug.log('agent.spawn', 'worktree-fallback-cwd', {
@@ -679,6 +787,19 @@ export async function dispatchAgent(
     ...(runInBackground ? { background: true } : {}),
   });
 
+  // Terminal release for this dispatch's reserved fan-out slot: the
+  // registry fires this exactly once per task when it reaches a
+  // terminal state (done/error/aborted); until then the slot counts as
+  // occupied against this session's ceiling above.
+  if (fanoutSession !== undefined) {
+    const fanoutSlotSession = fanoutSession;
+    const fanoutSlotSubscription = globalAgentRegistry.onTaskDone((task) => {
+      if (!task || task.id !== handle.task.id) return;
+      fanoutSlotSubscription.dispose();
+      releaseBackgroundFanoutSlot(fanoutSlotSession);
+    });
+    fanoutSession = undefined;  // the terminal subscription owns the release now
+  }
   // Forward parent abort to the spawned task. The registry owns the
   // child's controller; we just chain ours into it.
   if (opts.signal) {
@@ -907,4 +1028,9 @@ export async function dispatchAgent(
     ...(childCwd ? { cwd: childCwd } : {}),
     ...(appliedIsolation ? { isolation: appliedIsolation } : {}),
   };
+  } finally {
+    // The registered task owns its slot after the handoff above. Every
+    // pre-registration throw leaves fanoutSession set and releases it here.
+    releaseReservedFanoutSlot();
+  }
 }

package/src/skills/tools/msg-ask.ts

@@ -0,0 +1,100 @@
+import type { LLMToolSpec } from '../../llm.js';
+import { openMsgStore, validateMessageEnvelope, type Message, type MsgStore } from '../../msg/msg-store.js';
+
+export interface MsgAskDeps {
+  openStore?: () => MsgStore;
+  sleep?: (ms: number) => Promise<void>;
+  monotonicNow?: () => number;
+  wallNow?: () => number;
+  signal?: AbortSignal;
+}
+
+export interface MsgAskResult extends Record<string, unknown> {
+  output: string;
+  ok: boolean;
+  question: Message;
+  reply: Message | null;
+}
+
+export function buildMsgAskTool(): LLMToolSpec {
+  return {
+    name: 'MsgAsk',
+    description: 'Post a durable seat question, then wait for the first message whose replyTo points to it. A timeout or cancellation keeps the posted question and returns its ID for later follow-up.',
+    parameters: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Asking seat (ALL cannot send).' },
+        to: { type: 'string', description: 'Recipient seat.' },
+        question: { type: 'string', description: 'Nonempty question body.' },
+        waitSeconds: { type: 'integer', description: 'Wait 0–300 seconds; default 60.' },
+      },
+      required: ['from', 'to', 'question'],
+      additionalProperties: false,
+    },
+  };
+}
+
+export async function dispatchMsgAsk(rawArgs: Record<string, unknown>, deps: MsgAskDeps = {}): Promise<MsgAskResult> {
+  const waitRaw = rawArgs.waitSeconds ?? 60;
+  if (typeof waitRaw !== 'number' || !Number.isSafeInteger(waitRaw) || waitRaw < 0 || waitRaw > 300) {
+    throw new Error("'waitSeconds' must be an integer between 0 and 300");
+  }
+  const envelope = validateMessageEnvelope({
+    from: rawArgs.from,
+    to: rawArgs.to,
+    body: rawArgs.question,
+  });
+  if (envelope.to === 'ALL') throw new Error("'to' must name one recipient seat for MsgAsk");
+  const monotonicNow = deps.monotonicNow ?? (() => performance.now());
+  const wallNow = deps.wallNow ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const store = deps.openStore?.() ?? openMsgStore();
+  try {
+    if (deps.signal?.aborted) throw new Error('ask cancelled before posting');
+    const question = store.post(envelope);
+    const startedAt = monotonicNow();
+    const wallStartedAt = wallNow();
+    const deadline = startedAt + waitRaw * 1000;
+    const wallDeadline = Date.parse(question.createdAt) + waitRaw * 1000;
+    // Ledger timestamps are wall time while the wait budget is monotonic.
+    // If the two clocks diverge materially, preserve the question ID and
+    // make the uncertain result explicit instead of accepting a late reply.
+    const clockAdjusted = () => Math.abs((wallNow() - wallStartedAt) - (monotonicNow() - startedAt)) > 250;
+    let afterId = 0;
+    do {
+      if (deps.signal?.aborted) {
+        return { output: `MsgAsk #${question.id} posted; wait cancelled`, ok: false, question, reply: null };
+      }
+      if (clockAdjusted()) {
+        return { output: `MsgAsk #${question.id} posted; clock adjusted during wait, inspect linked replies`, ok: false, question, reply: null };
+      }
+      const replies = store.listReplies(question.id, 1000, afterId);
+      if (clockAdjusted()) {
+        return { output: `MsgAsk #${question.id} posted; clock adjusted during wait, inspect linked replies`, ok: false, question, reply: null };
+      }
+      for (const reply of replies) {
+        afterId = reply.id;
+        // A replyTo link alone does not prove the intended seat answered.
+        // A wall-clock timestamp can move backwards by less than the clock
+        // adjustment guard. Never accept a reply once monotonic time expired.
+        // This conservatively leaves replies observed late for follow-up.
+        if (reply.from === question.to && reply.to === question.from
+          && monotonicNow() <= deadline && Date.parse(reply.createdAt) <= wallDeadline) {
+          return { output: `MsgAsk #${question.id} → reply #${reply.id}: ${reply.body}`, ok: true, question, reply };
+        }
+      }
+      const remaining = deadline - monotonicNow();
+      if (deps.signal?.aborted) {
+        return { output: `MsgAsk #${question.id} posted; wait cancelled`, ok: false, question, reply: null };
+      }
+      if (remaining <= 0) {
+        return { output: `MsgAsk #${question.id} posted; no linked reply within ${waitRaw}s`, ok: false, question, reply: null };
+      }
+      // A full page may repeat forever. Yield so timers and AbortSignal
+      // callbacks can run before asking SQLite for the next page.
+      await sleep(replies.length === 1000 ? 0 : Math.min(100, remaining));
+    } while (true);
+  } finally {
+    store.close();
+  }
+}

package/src/skills/tools/ops-ledger.ts

@@ -3,7 +3,7 @@
 // OP TUI turns previously drove `elanous msg list/post/ack` and
 // `elanous release checklist list/move/set/add` through RunShell:
 // 1.3–2s of CLI startup per call, 30+ spawns per turn, and the CLI's
-// human-oriented stdout amplifying TUI screen defects. These eight
+// human-oriented stdout amplifying TUI screen defects. These
 // tools reuse the SAME durable services in-process —
 //
 //   • msg tools → src/msg/msg-store.ts (the SQLite ledger `elanous msg`
@@ -11,6 +11,7 @@
 //   • checklist tools → src/release-loop/checklist.ts + feature-store.ts
 //     (the same per-version ledger, claim history, seat/OP move rules)
 //
+// MsgAsk joins this family through msg-ask.ts; the other dispatchers live here.
 // The permission and audit contract is preserved 1:1:
 //   • writes record the actor from ELANOUS_TRACK (seat identity),
 //   • ChecklistMove keeps the CLI routing — anonymous (no ELANOUS_TRACK)

package/src/skills/tools/schedule-wakeup.ts

@@ -41,6 +41,17 @@ export const WAKEUP_MAX_CALLS_PER_TURN = 6;
 export const WAKEUP_REPEAT_INVALID_ERROR =
   'repeatMinutes 는 반복 간격(분 · 1 이상)이다 — 한 번만 깨우려면 repeatMinutes 를 빼거나 0 으로 두고 delaySeconds 또는 at 만 줘라';
 
+function formatWakeupTimeConflictError(req: ScheduleWakeupRequest): string {
+  const corrected = { ...req };
+  delete corrected.at;
+  delete corrected.atProvided;
+  return `at 과 delaySeconds 는 둘 중 하나만 줄 수 있다 — 교정 인자 예시(at 을 빼고 delaySeconds 사용): ${JSON.stringify(corrected)}. 같은 인자를 다시 보내지 말고 이 교정 인자로 한 번만 재시도하라`;
+}
+
+function canonicalToolArgs(args: Record<string, unknown>): string {
+  return JSON.stringify(Object.fromEntries(Object.entries(args).sort(([a], [b]) => a.localeCompare(b))));
+}
+
 export type WakeupTimerHandle = unknown;
 
 export interface WakeupEntry {
@@ -79,7 +90,9 @@ export interface WakeupSchedulerDeps {
 
 export type ScheduleWakeupRequest = {
   /** «HH:MM»(로컬 시각 · 지났으면 내일). delaySeconds 와 둘 중 하나. */
-  at?: string;
+  at?: unknown;
+  /** Host tool must preserve property presence even when the provider sent a non-string value. */
+  atProvided?: boolean;
   delaySeconds?: number;
   reason: string;
   /** 반복 간격(분). 첫 발화는 at/delaySeconds — 둘 다 없으면 지금부터 repeatMinutes 뒤. 0 = 일회성(생략과 같다). */
@@ -93,7 +106,7 @@ export type ScheduleWakeupResult =
 export type CancelWakeupResult = { ok: true } | { ok: false; error: string; capped?: boolean };
 
 export interface WakeupScheduler {
-  schedule(req: ScheduleWakeupRequest): ScheduleWakeupResult;
+  schedule(req: ScheduleWakeupRequest, requestKey?: string): ScheduleWakeupResult;
   list(): WakeupEntry[];
   cancel(id: string): boolean;
   /** cancel 과 같되 거부 사유(없는 id · 턴 상한)를 값으로 낸다 — LLM 도구가 쓴다. */
@@ -151,12 +164,24 @@ export function createWakeupScheduler(deps: WakeupSchedulerDeps): WakeupSchedule
   const maxCallsPerTurn = deps.maxCallsPerTurn ?? WAKEUP_MAX_CALLS_PER_TURN;
   let callTurnKey: string | null = null;
   let callCount = 0;
+  const conflictErrors = new Map<string, string>();
+
+  const readTurnId = (): string | null => deps.currentTurnId?.() ?? null;
 
-  /** 한 턴 호출 상한 — 넘었으면 거부 문구, 아니면 null. 턴 경계를 모르면(currentTurnId 없음) 걸지 않는다. */
-  const loopCapError = (action: 'schedule' | 'cancel'): string | null => {
-    if (!deps.currentTurnId) return null;
-    const turnId = deps.currentTurnId() ?? 'none';
-    if (turnId !== callTurnKey) { callTurnKey = turnId; callCount = 0; }
+  /** 한 턴 호출 상한 — 넘었으면 거부 문구, 아니면 null. 턴 경계가 unknown 이면 cap·dedupe 상태를 버린다. */
+  const loopCapError = (action: 'schedule' | 'cancel', observedTurnId = readTurnId()): string | null => {
+    if (observedTurnId === null) {
+      callTurnKey = null;
+      callCount = 0;
+      conflictErrors.clear();
+      return null;
+    }
+    const turnId = observedTurnId;
+    if (turnId !== callTurnKey) {
+      callTurnKey = turnId;
+      callCount = 0;
+      conflictErrors.clear();
+    }
     callCount += 1;
     if (callCount <= maxCallsPerTurn) return null;
     log('tui.wakeup', 'loop-capped', { turnId, count: callCount, max: maxCallsPerTurn, action });
@@ -252,20 +277,35 @@ export function createWakeupScheduler(deps: WakeupSchedulerDeps): WakeupSchedule
   };
 
   return {
-    schedule(req) {
+    schedule(req, requestKey) {
       const t = now();
       const reason = (req.reason ?? '').replace(/\s+/g, ' ').trim();
       const reject = (error: string): ScheduleWakeupResult => {
         log('tui.wakeup', 'rejected', { id: null, reason: 'invalid', error });
         return { ok: false, error };
       };
-      const capped = loopCapError('schedule');
+      // Every schedule attempt consumes the per-turn budget before validation.
+      const turnId = readTurnId();
+      const capped = loopCapError('schedule', turnId);
       if (capped) return { ok: false, error: capped };
+      // Presence is the contract: invalidly typed `at` values from the host
+      // must still conflict with delaySeconds rather than silently disappear.
+      const hasAt = req.atProvided ?? req.at !== undefined;
+      const hasDelay = req.delaySeconds !== undefined;
+      if (hasAt && hasDelay) {
+        const key = requestKey ?? canonicalToolArgs(req as Record<string, unknown>);
+        if (turnId !== null) {
+          const previousError = conflictErrors.get(key);
+          if (previousError !== undefined) {
+            return { ok: false, error: `${previousError} — 같은 충돌 인자의 재시도는 억제했다` };
+          }
+          if (conflictErrors.size < maxCallsPerTurn) conflictErrors.set(key, formatWakeupTimeConflictError(req));
+        }
+        const error = formatWakeupTimeConflictError(req);
+        return reject(error);
+      }
       if (!reason) return reject('reason 이 비었다 — 깨어나서 무엇을 할지 한 줄로 적어라');
       if (entries.size >= maxEntries) return reject(`예약 상한 ${maxEntries}개 — list 로 보고 cancel 뒤 다시`);
-      const hasAt = typeof req.at === 'string' && req.at.trim() !== '';
-      const hasDelay = typeof req.delaySeconds === 'number';
-      if (hasAt && hasDelay) return reject('at 과 delaySeconds 는 둘 중 하나만');
       let repeatMs: number | undefined;
       // ⭐ 0 = 일회성(생략과 같다) — 모델이 «한 번만»을 0 으로 부른다(라이브 실측). 음수·NaN·1 미만 소수는 거부.
       if (req.repeatMinutes !== undefined && req.repeatMinutes !== 0) {
@@ -276,7 +316,8 @@ export function createWakeupScheduler(deps: WakeupSchedulerDeps): WakeupSchedule
       }
       let dueAt: number;
       if (hasAt) {
-        const resolved = resolveWakeupAt(req.at!, t);
+        if (typeof req.at !== 'string') return reject(`at 은 «HH:MM» 문자열이어야 한다 — 받은 값 ${JSON.stringify(req.at)}`);
+        const resolved = resolveWakeupAt(req.at, t);
         if (resolved === null) return reject(`at 은 «HH:MM»(24시간) 꼴 — 받은 값 ${JSON.stringify(req.at)}`);
         dueAt = resolved;
       } else if (hasDelay) {
@@ -342,7 +383,7 @@ export function buildScheduleWakeupHostTool(scheduler: WakeupScheduler): LLMTool
     name: SCHEDULE_WAKEUP_TOOL_NAME,
     description:
       'Wake THIS TUI later with an internal turn: when you would write «다음 점검 HH:MM» and end the turn, call this instead so the check actually happens. '
-      + 'action=schedule (default) needs reason plus one of at ("HH:MM" local, past → tomorrow) / delaySeconds (≥60) / repeatMinutes (≥1; repeats expire after 7 days). '
+      + 'action=schedule (default) needs reason plus one of at ("HH:MM" local, past → tomorrow) / delaySeconds (≥60) / repeatMinutes (≥1; repeats expire after 7 days). Never provide both at and delaySeconds; the schema requires one timing variant. '
       + 'ONE-SHOT (wake once): give only delaySeconds or at and OMIT repeatMinutes (0 also means one-shot). Set repeatMinutes only when you really want it to repeat. '
       + `action=list shows pending wakeups; action=cancel needs id. Limits: ≥60s ahead, ≤7 days, at most 5 pending, at most ${WAKEUP_MAX_CALLS_PER_TURN} schedule/cancel calls per turn. `
       + 'If the TUI is busy or the human is typing at that time it retries once a minute later, then gives up (repeats move to the next tick). '
@@ -358,6 +399,11 @@ export function buildScheduleWakeupHostTool(scheduler: WakeupScheduler): LLMTool
         id: { type: 'string', description: 'Wakeup id for action=cancel (from schedule/list).' },
       },
       required: [],
+      oneOf: [
+        { not: { anyOf: [{ required: ['at'] }, { required: ['delaySeconds'] }] } },
+        { required: ['at'], not: { required: ['delaySeconds'] } },
+        { required: ['delaySeconds'], not: { required: ['at'] } },
+      ],
     },
     handler: async (args) => {
       const action = typeof args.action === 'string' ? args.action : 'schedule';
@@ -368,12 +414,15 @@ export function buildScheduleWakeupHostTool(scheduler: WakeupScheduler): LLMTool
         return r.ok ? { cancelled: id } : { error: r.error };
       }
       if (action !== 'schedule') return { error: `unknown action ${JSON.stringify(action)}` };
-      const result = scheduler.schedule({
+      const atProvided = Object.prototype.hasOwnProperty.call(args, 'at');
+      const request: ScheduleWakeupRequest = {
         reason: typeof args.reason === 'string' ? args.reason : '',
-        ...(typeof args.at === 'string' ? { at: args.at } : {}),
+        atProvided,
+        ...(atProvided ? { at: args.at } : {}),
         ...(typeof args.delaySeconds === 'number' ? { delaySeconds: args.delaySeconds } : {}),
         ...(typeof args.repeatMinutes === 'number' ? { repeatMinutes: args.repeatMinutes } : {}),
-      });
+      };
+      const result = scheduler.schedule(request, canonicalToolArgs(args));
       return result.ok ? { scheduled: describeEntry(result.entry) } : { error: result.error };
     },
   };

package/src/steward/hold-hygiene.ts

@@ -5,7 +5,7 @@ import { opSeatStatePath, readTrafficSignal } from '../seat-loop/traffic-signal.
 
 const SEATS = ['OP', 'MK', 'TC', 'UX'] as const;
 type Seat = typeof SEATS[number];
-export type HygieneCell = { id: string; owner?: string | null; status: string };
+export type HygieneCell = { id: string; owner?: string | null; status: string; title?: string };
 export type HygieneNotice = { to: Seat; key: string; body: string };
 export type HygieneDeps = {
   root: string;
@@ -45,7 +45,7 @@ export function starvingCycles(log: string): { reasons: Record<string, number> }
   return { reasons };
 }
 
-type HoldMeta = { id?: unknown; op?: unknown; reason?: unknown; until?: unknown };
+type HoldMeta = { id?: unknown; op?: unknown; reason?: unknown; until?: unknown; kind?: unknown; confirmedAt?: unknown; at?: unknown; title?: unknown };
 function holdMetadata(path: string): Map<string, HoldMeta> {
   const latest = new Map<string, HoldMeta>();
   for (const line of (readOptional(path) ?? '').split(/\r?\n/)) {
@@ -65,6 +65,10 @@ function untilTime(value: unknown): number | null {
   return Number.isFinite(time) ? time : null;
 }
 
+function confirmedTime(value: unknown): number | null {
+  return typeof value === 'string' && /^\d{12}$/.test(value) ? untilTime(value) : null;
+}
+
 export function inspectHoldHygiene(deps: HygieneDeps): HygieneNotice[] {
   const notices: HygieneNotice[] = [];
   const dir = deps.dispatcherDir ?? opSeatStatePath('feeder');
@@ -88,11 +92,25 @@ export function inspectHoldHygiene(deps: HygieneDeps): HygieneNotice[] {
     if (!SEATS.some(seat => seat === owner)) continue;
     const meta = metadata.get(cell.id);
     const reason = meta?.op === 'add' && typeof meta.reason === 'string' ? meta.reason.trim() : '';
-    const expiry = untilTime(meta?.until);
-    const expired = typeof meta?.until === 'string' && meta.until.trim() !== '' && (expiry === null || expiry <= deps.now.getTime());
-    if (reason && !expired) continue;
+    let attention = '';
+    if (meta?.kind === '손작업') {
+      const confirmed = confirmedTime(meta.confirmedAt ?? meta.at);
+      if (confirmed === null) attention = '재확인 시각 없음';
+      else if (deps.now.getTime() - confirmed >= 24 * 60 * 60_000) attention = '24h 재확인 지연';
+    } else if (meta?.kind === '재발사금지') {
+      if (typeof meta.title !== 'string' || !meta.title || typeof cell.title !== 'string' || !cell.title) attention = '제목 기준 확인 불가';
+      else if (cell.title !== meta.title) attention = '칸 제목 변경';
+    } else if (meta?.kind === '선행대기' || meta?.kind === undefined || meta?.kind === '') {
+      const expiry = untilTime(meta?.until);
+      if (expiry === null) attention = 'until 확인 불가';
+      else if (expiry <= deps.now.getTime()) attention = `until ${String(meta?.until)} 지남`;
+    } else attention = 'hold 종류 확인 불가';
+    if (reason && !attention) continue;
+    const guidance = meta?.kind === '손작업' ? '재확인 시각·사유를 판단해 OP에 알려 주세요.'
+      : meta?.kind === '재발사금지' ? '칸 제목과 기준 제목·사유를 대조해 OP에 알려 주세요.'
+        : '풀기/유지(사유·until)를 판단해 OP에 알려 주세요.';
     notices.push({ to: owner as Seat, key: `hold:${cell.id}:${owner}`,
-      body: `노랑 칸 ${cell.id} traffic hold: ${!reason ? '사유 없음' : `사유 ${reason}`} ${expired ? `· until ${String(meta?.until)} 지남` : ''}. 풀기/유지(사유·until)를 판단해 OP에 알려 주세요. 자동 해제하지 않습니다.` });
+      body: `노랑 칸 ${cell.id} traffic hold: ${!reason ? '사유 없음' : `사유 ${reason}`} ${attention ? `· ${attention}` : ''}. ${guidance} 자동 해제하지 않습니다.` });
   }
   return notices;
 }

package/src/steward/release-day.ts

@@ -15,16 +15,19 @@ export interface ReleaseDayDecision {
   reason?: string;
 }
 
-/** The release record, rather than publishAt (a planned time), opens green-back. */
+/** Green-back waits for both the scheduled publish end and the actual publication record. */
 export function decideReleaseDayPhase(schedule: ReleaseSchedule, now: Date, publishedAt: string | null): ReleaseDayDecision {
   const cut = Date.parse(schedule.cutAt);
   const land = schedule.landBy ? Date.parse(schedule.landBy) : cut;
   const gate = cut - 30 * 60_000;
   const time = now.getTime();
+  const published = publishedAt ? Date.parse(publishedAt) : Number.NaN;
+  const publishEnd = schedule.publishAt ? Date.parse(schedule.publishAt) : published;
+  const greenAt = Number.isFinite(published) && Number.isFinite(publishEnd) ? Math.max(published, publishEnd) : Number.NaN;
   let phase: ReleaseDayPhase = 'none';
   let dueAt: string | null = null;
-  if (publishedAt && time >= Date.parse(publishedAt)) {
-    phase = 'green-back'; dueAt = publishedAt;
+  if (time >= greenAt) {
+    phase = 'green-back'; dueAt = publishEnd >= published ? schedule.publishAt ?? publishedAt : publishedAt;
   } else if (time >= cut) {
     phase = 'cut-run'; dueAt = schedule.cutAt;
   } else if (time >= land) {
@@ -133,6 +136,7 @@ export function runReleaseDayShadow(deps: ReleaseDayShadowDeps = {}): ReleaseDay
         continue;
       }
       const publishedAt = publication.kind === 'published' ? publication.at : null;
+      // The steward graph tick records this judgment only; release CLI actions remain outside this shadow boundary.
       const decision = decideReleaseDayPhase(schedule, now, publishedAt);
       let recorded = false;
       if (decision.phase !== 'none') {