approval-md 0.4.5 → 0.4.7

package/dist/src/cli/channel-telegram.d.ts

@@ -489,7 +489,8 @@ export declare const DISPATCH_LOUD_ATTEMPTS = 3;
  */
 export declare const DISPATCH_RETENTION_MS: number;
 /**
- * The line that introduces the first batch a listener process sends (APRV-196).
+ * The one message that introduces the first batch a listener process sends
+ * (APRV-196). Two lines, sent together by `announce`, the first in bold.
  *
  * **Why a banner and not an edit of the earlier copies.** The incident was a
  * restart re-sending five pending requests with no warning, on top of five
@@ -505,19 +506,42 @@ export declare const DISPATCH_RETENTION_MS: number;
  * (`actionRefOf` in `channels/telegram.ts`), so a human who taps the copy they
  * can see decides the request they meant.
  *
- * It says "started" rather than "restarted" because a listener cannot tell the
- * two apart, having deliberately kept nothing that would let it, and a first
- * start that claimed to be a restart would be this channel's own text lying
- * about the system's history.
+ * **The words are a resident's, not the system's.** The reader is whoever
+ * holds the phone, so the banner is one short message in plain words: how many
+ * requests are still waiting, and whether the buttons on the older messages
+ * above still work. It names no process, no log and no cycle, and it says
+ * neither "started" nor "restarted": a listener cannot tell the two apart,
+ * having deliberately kept nothing that would let it, so the text claims only
+ * what is true either way (these requests are still waiting). The old third
+ * line, about where the pending set is read from, is gone; it described the
+ * runtime to someone who only needs to know which button to press.
  *
  * **With the stale-copy fallback off (APRV-456)** the second line says the
- * opposite, because the earlier copies' buttons no longer decide anything: a
- * relayed listener refuses a nonce it is not holding (`nonce-not-issued`), so
- * the banner tells the approver to use the copies below it. A banner that kept
+ * opposite, because the earlier copies' buttons no longer work: a relayed
+ * listener refuses a nonce it is not holding (`nonce-not-issued`), so the
+ * banner tells the approver to use the buttons below it. A banner that kept
  * promising working older copies would be this channel's own text sending the
  * approver to a button that refuses them.
  */
 export declare function bannerLines(pending: number, staleCopy?: boolean): string[];
+/**
+ * The reminder a collapsed re-delivery opens with, in place of the banner
+ * (P-9).
+ *
+ * Before this, a restart with two stale requests and one live one sent the
+ * stale summary first and the {@link bannerLines} banner second, and the banner
+ * counted only the cards after it: "1 request is still waiting" with three
+ * pending and the summary of the other two directly above. Two reminders, the
+ * more verbose one first, and a count that read as wrong. Now the summary IS the
+ * reminder: its first line counts everything this cycle re-sends (`pending`,
+ * collapsed and carded together), and the banner is skipped.
+ *
+ * `following` is how many requests get their own card after the summary. When
+ * there are any, the second line says so and says whether the buttons on older
+ * messages still work, which is what the banner it replaces said (APRV-456).
+ * When there are none, the summary is the whole restart and nothing follows.
+ */
+export declare function staleReminderLines(pending: number, following: number, staleCopy?: boolean): string[];
 /**
  * Whether APRV-196's stale-copy fallback is on for a listener launched with
  * this `--api-base` and this `--no-stale-copy` (APRV-456).
@@ -535,34 +559,73 @@ export declare function bannerLines(pending: number, staleCopy?: boolean): strin
  */
 export declare function staleCopyFor(apiBase: string | null, noStaleCopy: boolean): boolean;
 /**
- * The summary line that precedes a paced send, and the body of `/queue`.
- *
- * One message, and everything in it is arithmetic on the verified log at the
- * instant it is written: how many requests are pending, how long the oldest has
- * waited, and which classes they are. Nothing is remembered between calls, so
- * two summaries a minute apart can disagree only because the log moved.
- *
- * The class tally is the part worth the space. The count alone says how much
- * work is waiting; the classes say what KIND of work, which is what tells an
- * approver whether the queue is six identical `network.call`s they can walk
- * through or one `policy.edit` they should read carefully.
+ * The launch variable that turns study mode on (amended SPEC.md §8, the study
+ * record). Generic on purpose: the core is a public spec and names no study.
+ * A hosted deployment writes it into the listener's environment for the
+ * tenants a study covers; nothing else sets it.
+ */
+export declare const STUDY_MODE_ENV = "APPROVAL_STUDY_MODE";
+/**
+ * Whether `env` turns study mode on: the value is exactly `1`, and anything
+ * else (unset, blank, `true`, ` 1`, `0`) is off. Called once, by
+ * {@link prepareListen}; the channel keeps the answer for its lifetime, so a
+ * change takes effect only when the listener restarts.
+ */
+export declare function studyModeFor(env: NodeJS.ProcessEnv): boolean;
+/**
+ * The count line a paced cycle sends when the pending set has grown, and the
+ * header of `/queue` (APRV-216), in a resident's words (P-9).
+ *
+ * One line, and everything in it is arithmetic on the verified log at the
+ * instant it is written: how many requests are waiting and how long the oldest
+ * has waited. Nothing is remembered between calls, so two summaries a minute
+ * apart can disagree only because the log moved.
+ *
+ * Before P-9 it also carried a class tally ("communicate.email.external ×3").
+ * The tally told an operator what kind of work was queued, and told a resident
+ * nothing they could read; the kind of each request is on its own card, and
+ * `/queue` now lists each by the agent's own summary ({@link queueLines}).
+ *
+ * The oldest is the one asked longest ago, whatever order `requests` is in:
+ * `/queue` passes the set in presentation order ({@link orderPending}, live
+ * newest first), where the first entry is the NEWEST, and a header that read
+ * the first entry's age called the newest one the oldest.
  */
 export declare function summaryLines(requests: ChannelRequest[], now: string): string[];
+/**
+ * The reminder a paced listener's first cycle opens with (P-9).
+ *
+ * Paced is the product default (APRV-216), and a restart there used to open
+ * with the bare count line and then one card. Nothing in it said this was a
+ * reminder, or whether the buttons on older messages above still worked, which
+ * matters most behind a relay, where they do not (APRV-456). So the first
+ * cycle's line is a reminder in the burst banner's words ({@link bannerLines}):
+ * how many are waiting, how many are below, and what the older buttons do.
+ *
+ * `shown` is how many requests this cycle puts below it: one, or a digest
+ * group. With the stale-copy fallback on, older buttons decide only while their
+ * request is the one being shown, so when fewer are shown than are pending the
+ * line says only the ones below work right now (fold round 1, S1). Later cycles that find the set has grown send {@link summaryLines}
+ * instead, which is a count and not a reminder.
+ */
+export declare function pacedReminderLines(pending: number, shown: number, staleCopy?: boolean): string[];
 /**
  * `/queue`'s reply: the summary, then one numbered line per pending request.
  *
  * Derived, like the summary, from the verified log at reply time and not from
  * anything this process is holding: the numbering is positional and names no
  * button, so a stale copy of this list cannot be used to decide anything. The
- * marker says which one this listener has selected and once delivered, because
- * the question `/queue` is usually asked to answer is "what else is there
- * besides the one I am looking at" — and, since APRV-256, its unhappy twin,
- * "where is the one I am supposed to be looking at".
- *
- * The footer answers that second question the only honest way available to a
- * process whose knowledge of the chat ends at "a send returned success": it
- * says what was sent, says it cannot tell whether the card survived, and then
- * spends its remaining words on recovery rather than reassurance.
+ * marker says which one was sent earlier, because the question `/queue` is
+ * usually asked to answer is "what else is there besides the one I am looking
+ * at" and, since APRV-256, its unhappy twin, "where is the one I am supposed to
+ * be looking at".
+ *
+ * P-9: each line is the agent's own summary and its age, under the label that
+ * says the summary is the agent's and unchecked. Before P-9 each line was the
+ * action key, the task id, the class and the age, and in real use the first
+ * two are `hook:<session uuid>:<tool_use_id>…`, two long raw ids per line. The
+ * three recovery paragraphs are two short lines: what /skip and /next do, and
+ * that neither answers anything.
  */
 export declare function queueLines(requests: ChannelRequest[], now: string, shown: readonly string[]): string[];
 /**
@@ -992,16 +1055,32 @@ export declare function supersededPending(requests: ChannelRequest[]): Set<strin
  */
 export declare function orderPending(requests: ChannelRequest[], now: string): ChannelRequest[];
 /**
- * The computed lines a collapsed re-delivery leads with (APRV-287).
+ * The computed lines a collapsed re-delivery leads with (APRV-287), in a
+ * resident's words (P-9).
  *
  * `superseded` is the subset a newer pending request replaced (APRV-425), and
- * the first line states the split rather than claiming every member is old.
- * Before this the line said "all older than the hook's wait plus its retry
- * grace", which stopped being true the moment the collapse widened: a message
- * that overstates what it collapsed is the stale-documentation failure in
- * message form, and this one is read by the person deciding.
+ * the line states the split rather than claiming every member is old. Before
+ * APRV-425 it said every member was past the hook's wait, which stopped being
+ * true the moment the collapse widened: a message that overstates what it
+ * collapsed is the stale-documentation failure in message form, and this one is
+ * read by the person deciding.
+ *
+ * Before P-9 these lines also spelled out the hook's wait and retry grace in
+ * seconds and minutes, a tally of class names, and a sentence about log events
+ * and identical retries. The reader is whoever holds the phone, so what is left
+ * is the one thing they need: how many are listed, and why nobody needs an
+ * answer to them now. The age of each one moves onto its own line
+ * ({@link staleAges}).
+ */
+export declare function staleLines(requests: ChannelRequest[], _now: string, superseded?: ReadonlySet<string>): string[];
+/**
+ * How long ago each collapsed request was asked, in the order given (P-9).
+ *
+ * Computed from the verified log's own `requested_ts`, like the rest of the
+ * summary, and rendered beside each member's claimed summary line so the
+ * resident can tell the requests apart without an action key.
  */
-export declare function staleLines(requests: ChannelRequest[], now: string, superseded?: ReadonlySet<string>): string[];
+export declare function staleAges(requests: readonly ChannelRequest[], now: string): string[];
 /**
  * Put the requests nobody is waiting on into ONE message, and hand back the
  * ones that still get a message each (APRV-287, widened by APRV-425).