bareloop 0.54.1 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/bareloop.context.md +65 -6
  3. package/package.json +3 -3
  4. package/src/authorflow.js +148 -46
  5. package/src/authoring.js +21 -4
  6. package/src/authorjob.js +82 -3
  7. package/src/authorreadout.js +20 -3
  8. package/src/authorrun.js +1 -1
  9. package/src/authorscout.js +9 -6
  10. package/src/cardschedule.js +42 -0
  11. package/src/checkpick.js +576 -0
  12. package/src/checksuggest.js +28 -0
  13. package/src/checkwords.js +25 -0
  14. package/src/cli.js +1 -1
  15. package/src/config.js +24 -1
  16. package/src/declaredclose.js +1 -1
  17. package/src/destpoint.js +149 -0
  18. package/src/draftspend.js +39 -0
  19. package/src/factwords.js +14 -1
  20. package/src/job.js +81 -1
  21. package/src/jobblock.js +9 -0
  22. package/src/labelscan.js +11 -0
  23. package/src/launcher.js +3 -2
  24. package/src/mcpchecks.js +52 -0
  25. package/src/mcppick.js +36 -0
  26. package/src/mcpsources.js +77 -0
  27. package/src/mcpuse.js +97 -0
  28. package/src/natural.js +23 -0
  29. package/src/pagemap.js +5 -2
  30. package/src/panel/authorroutes.js +90 -15
  31. package/src/panel/authorsession.js +183 -21
  32. package/src/panel/index.html +686 -26
  33. package/src/panel/jobgrid.js +117 -0
  34. package/src/panel/jobplan.js +31 -15
  35. package/src/panel/scheduler.js +80 -13
  36. package/src/panel/schedules.js +189 -28
  37. package/src/panel/schedulestart.js +44 -13
  38. package/src/panel/server.js +419 -32
  39. package/src/panel/settingsroutes.js +133 -3
  40. package/src/panel/status.js +19 -1
  41. package/src/panel/tickets.js +44 -0
  42. package/src/pickrecord.js +145 -0
  43. package/src/plan.js +31 -2
  44. package/src/planrun.js +71 -15
  45. package/src/prcheckout.js +259 -0
  46. package/src/readshim.js +3 -2
  47. package/src/revises.js +56 -0
  48. package/src/rubricstep.js +62 -16
  49. package/src/run.js +10 -1
  50. package/src/runexport.js +2 -0
  51. package/src/runlist.js +3 -2
  52. package/src/schedulewords.js +46 -4
  53. package/src/source.js +81 -7
  54. package/src/stepmcp.js +86 -0
  55. package/src/ticket.js +113 -0
  56. package/src/ticketfilter.js +76 -0
  57. package/src/ticketlabels.js +79 -0
  58. package/src/ticketmcp.js +111 -0
  59. package/src/ticketnext.js +35 -0
  60. package/src/ticketrepo.js +98 -0
  61. package/src/ticketschedule.js +32 -0
  62. package/src/ticketshape.js +45 -0
  63. package/src/tools.js +9 -0
  64. package/src/trigger.js +14 -2
  65. package/src/triggerclock.js +7 -3
  66. package/src/triggerfiles.js +19 -11
  67. package/src/triggertickets.js +244 -0
  68. package/src/userrun.js +145 -9
  69. package/src/validate.js +3 -1
  70. package/src/worktree.js +43 -1
  71. package/types/authorflow.d.ts +128 -28
  72. package/types/authorjob.d.ts +16 -3
  73. package/types/authorreadout.d.ts +9 -2
  74. package/types/authorscout.d.ts +4 -2
  75. package/types/cardschedule.d.ts +24 -0
  76. package/types/checkpick.d.ts +297 -0
  77. package/types/checksuggest.d.ts +30 -0
  78. package/types/checkwords.d.ts +14 -0
  79. package/types/config.d.ts +7 -0
  80. package/types/destpoint.d.ts +87 -0
  81. package/types/draftspend.d.ts +16 -0
  82. package/types/factwords.d.ts +7 -0
  83. package/types/job.d.ts +13 -0
  84. package/types/jobblock.d.ts +9 -0
  85. package/types/labelscan.d.ts +7 -0
  86. package/types/launcher.d.ts +2 -2
  87. package/types/mcpchecks.d.ts +8 -0
  88. package/types/mcppick.d.ts +33 -0
  89. package/types/mcpsources.d.ts +51 -0
  90. package/types/mcpuse.d.ts +15 -0
  91. package/types/natural.d.ts +2 -0
  92. package/types/pagemap.d.ts +2 -1
  93. package/types/panel/authorroutes.d.ts +11 -2
  94. package/types/panel/authorsession.d.ts +58 -3
  95. package/types/panel/jobgrid.d.ts +405 -0
  96. package/types/panel/jobplan.d.ts +10 -4
  97. package/types/panel/scheduler.d.ts +7 -2
  98. package/types/panel/schedules.d.ts +124 -4
  99. package/types/panel/schedulestart.d.ts +21 -3
  100. package/types/panel/server.d.ts +427 -6
  101. package/types/panel/settingsroutes.d.ts +4 -2
  102. package/types/panel/status.d.ts +16 -2
  103. package/types/panel/tickets.d.ts +61 -0
  104. package/types/pickrecord.d.ts +88 -0
  105. package/types/plan.d.ts +1 -0
  106. package/types/prcheckout.d.ts +151 -0
  107. package/types/readshim.d.ts +4 -3
  108. package/types/revises.d.ts +23 -0
  109. package/types/rubricstep.d.ts +14 -5
  110. package/types/run.d.ts +18 -1
  111. package/types/runlist.d.ts +6 -3
  112. package/types/schedulewords.d.ts +29 -2
  113. package/types/source.d.ts +40 -4
  114. package/types/stepmcp.d.ts +40 -0
  115. package/types/ticket.d.ts +114 -0
  116. package/types/ticketfilter.d.ts +34 -0
  117. package/types/ticketlabels.d.ts +44 -0
  118. package/types/ticketmcp.d.ts +84 -0
  119. package/types/ticketnext.d.ts +33 -0
  120. package/types/ticketrepo.d.ts +118 -0
  121. package/types/ticketschedule.d.ts +21 -0
  122. package/types/ticketshape.d.ts +37 -0
  123. package/types/tools.d.ts +1 -0
  124. package/types/trigger.d.ts +9 -1
  125. package/types/triggerclock.d.ts +6 -2
  126. package/types/triggerfiles.d.ts +13 -5
  127. package/types/triggertickets.d.ts +110 -0
  128. package/types/userrun.d.ts +50 -0
  129. package/types/validate.d.ts +1 -0
  130. package/types/worktree.d.ts +19 -0
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Mask a text and measure it: the masked text, its sha256 and byte length, and how many secret shapes it carried.
3
+ * @param {string} raw @returns {{text: string, sha256: string, bytes: number, masked: number}}
4
+ */
5
+ export function maskTicketText(raw: string): {
6
+ text: string;
7
+ sha256: string;
8
+ bytes: number;
9
+ masked: number;
10
+ };
11
+ /**
12
+ * A ticket from the text of a PAGE (barebrowse act mode). Weaker than an MCP read, said plainly: the body may be missing (fwd F89: a page reader drops it),
13
+ * labels are null (not read from a page), and state is `closed` only when the text says `Closed`, else `unknown`.
14
+ * @param {string} rawText @param {string} url @returns {Ticket}
15
+ */
16
+ export function ticketFromPage(rawText: string, url: string): Ticket;
17
+ /**
18
+ * A ticket from an MCP `issue_read` reply (a JSON document on GitHub's server; anything else keeps its text, with the first line as the title and the
19
+ * state and labels unknown).
20
+ * @param {string} rawText @param {string} url @param {number} number
21
+ * @param {Ticket['record']} record @returns {Ticket}
22
+ */
23
+ export function ticketFromMcp(rawText: string, url: string, number: number, record: Ticket["record"]): Ticket;
24
+ /**
25
+ * The pull request a `pull_request_read` ticket froze, as the object the checkout reads (`head.sha`, `base.ref`, `base.sha`): the parsed, MASKED reply (the same bytes the
26
+ * sha256 covers - a sha is not a secret shape, so masking leaves it whole). Null when the text is not a JSON object.
27
+ * @param {Ticket} ticket @returns {Record<string, any>|null}
28
+ */
29
+ export function prRecordOfTicket(ticket: Ticket): Record<string, any> | null;
30
+ /**
31
+ * Read one ticket, whatever its source. An MCP-backed row (`mcp` present) goes to the MCP reader; a page row to the page reader.
32
+ * @param {{mcp?: {server: string, tools: string[]}, listUrl?: string, number?: number, url?: string}} row
33
+ * @param {{configPath?: string, home?: string, timeoutMs?: number, fetchPage?: typeof fetchPageText}} [deps] test seams
34
+ * @returns {Promise<{ok: true, ticket: Ticket} | {ok: false, error: string}>}
35
+ */
36
+ export function readTicket(row: {
37
+ mcp?: {
38
+ server: string;
39
+ tools: string[];
40
+ };
41
+ listUrl?: string;
42
+ number?: number;
43
+ url?: string;
44
+ }, deps?: {
45
+ configPath?: string;
46
+ home?: string;
47
+ timeoutMs?: number;
48
+ fetchPage?: typeof fetchPageText;
49
+ }): Promise<{
50
+ ok: true;
51
+ ticket: Ticket;
52
+ } | {
53
+ ok: false;
54
+ error: string;
55
+ }>;
56
+ /**
57
+ * @typedef {object} Ticket
58
+ * @property {'mcp'|'page'} source
59
+ * @property {string} url the address of this ticket
60
+ * @property {number|null} number null = a page address that carries no ticket number (the grid row reads `#?`)
61
+ * @property {string} title
62
+ * @property {'open'|'closed'|'unknown'} state
63
+ * @property {string[]|null} labels null = not readable (a page); a priority filter finds none, and `unsure` never skips
64
+ * @property {string} text the MASKED text, as frozen
65
+ * @property {string} sha256 of the masked text's UTF-8 bytes
66
+ * @property {number} bytes
67
+ * @property {number} masked how many secret-shaped strings were masked (a count; never the values)
68
+ * @property {{server: string, exposed: string[], missing: Array<{server: string, tool: string}>, calls: Array<Record<string, any>>}|null} record the MCP read's own record (null for a page)
69
+ */
70
+ /** said on the plan card, in code-owned words, when a ticket comes from a page */
71
+ export const PAGE_TICKET_LIMIT_WORDS: "A ticket read from a page may lack its body, and its labels and state may be missing.";
72
+ export type Ticket = {
73
+ source: "mcp" | "page";
74
+ /**
75
+ * the address of this ticket
76
+ */
77
+ url: string;
78
+ /**
79
+ * null = a page address that carries no ticket number (the grid row reads `#?`)
80
+ */
81
+ number: number | null;
82
+ title: string;
83
+ state: "open" | "closed" | "unknown";
84
+ /**
85
+ * null = not readable (a page); a priority filter finds none, and `unsure` never skips
86
+ */
87
+ labels: string[] | null;
88
+ /**
89
+ * the MASKED text, as frozen
90
+ */
91
+ text: string;
92
+ /**
93
+ * of the masked text's UTF-8 bytes
94
+ */
95
+ sha256: string;
96
+ bytes: number;
97
+ /**
98
+ * how many secret-shaped strings were masked (a count; never the values)
99
+ */
100
+ masked: number;
101
+ /**
102
+ * the MCP read's own record (null for a page)
103
+ */
104
+ record: {
105
+ server: string;
106
+ exposed: string[];
107
+ missing: Array<{
108
+ server: string;
109
+ tool: string;
110
+ }>;
111
+ calls: Array<Record<string, any>>;
112
+ } | null;
113
+ };
114
+ import { fetchPageText } from './pagefetch.js';
@@ -0,0 +1,34 @@
1
+ /**
2
+ * @param {unknown} f the filter @param {{hasMcp?: boolean}} [o] `hasMcp: false` adds the "belongs to a job with an MCP" red
3
+ * @returns {Array<{code: string, path: string, detail: string}>} no entry = legal
4
+ */
5
+ export function ticketFilterReds(f: unknown, { hasMcp }?: {
6
+ hasMcp?: boolean;
7
+ }): Array<{
8
+ code: string;
9
+ path: string;
10
+ detail: string;
11
+ }>;
12
+ /**
13
+ * The facts a person-facing turn must not ask about (R5 finding F285): the confirm turn asked "which ticket, and is it P1?" in 5 of 10 live drafts. ONE owner of these words;
14
+ * the confirm prompt and the drafting prompt both carry them, for a Tickets job only.
15
+ * @returns {string}
16
+ */
17
+ export function ticketPerRunFacts(): string;
18
+ /**
19
+ * What the drafter is told when the job reads tickets (appended to the authoring prompt only then; a plain job's prompt is untouched).
20
+ * Adapted from fwd's `ticketFactsLines` (v0.29.0): the same MUST, the same "never invent a label".
21
+ * @returns {string}
22
+ */
23
+ export function ticketFilterBlock(): string;
24
+ /**
25
+ * The filter in code-owned plain words (the plan card, the Job tab): never model prose. Null when there is nothing to say.
26
+ * @param {any} f the (legal) filter @returns {string|null}
27
+ */
28
+ export function ticketFilterWords(f: any): string | null;
29
+ /** a legal filter, as the drafter is shown it: used in the prompt AND in every red's detail */
30
+ export const TICKET_FILTER_EXAMPLE: "{\"priority\": [\"P1\"], \"labels\": [\"bug\"]}";
31
+ /** the schema's description of the `ticketFilter` property (src/authorflow.js): REQUIRED when a job line names a priority or a label, never "optional" (F285, run-e1 shape) */
32
+ export const TICKET_FILTER_SCHEMA_WORDS: "REQUIRED when a job line names a priority or a label (leave it out only when none does). The person signs it; code decides at run start. Listing the line under \"refused\" does not filter anything: only this key does";
33
+ /** R9 (F122, fwd e89196e): the frozen ticket is read like any input, and reading is a grant; the DRAFTING turn is told (the person-facing confirm turn is not: it speaks of no tools). */
34
+ export const TICKET_READ_FACT: "A step that reads the ticket input still lists \"read\" in its tools: the ticket is already frozen at run start, but reading it is a grant, so a step without \"read\" cannot see it.";
@@ -0,0 +1,44 @@
1
+ /**
2
+ * One priority value from a ticket's labels: `P0`..`P3`; `unsure` when two different ones are present, or when a label names a priority on another scale
3
+ * (`priority/important-soon`) and no scale value is present; `none` when no label speaks of priority.
4
+ * @param {string[]} labels @returns {string}
5
+ */
6
+ export function priorityOf(labels: string[]): string;
7
+ /**
8
+ * The typed fields of a ticket read through `issue_read`: its JSON. A missing `labels` key means no labels (GitHub omits it, F98). Text that is not a JSON
9
+ * object is `ok:false`: never read as "no labels".
10
+ * @param {string} text @returns {{ok: true, labels: string[], state: string|null, title: string|null}|{ok: false}}
11
+ */
12
+ export function readTicketFields(text: string): {
13
+ ok: true;
14
+ labels: string[];
15
+ state: string | null;
16
+ title: string | null;
17
+ } | {
18
+ ok: false;
19
+ };
20
+ /**
21
+ * M13 piece 7 (9.4): the ONE reader of "the filter was unsure about this ticket", from a run.json input entry: true when its stored verdict ran with an `unsure`
22
+ * reason (also when the ticket was sent with Run it anyway and the filter's own verdict was unsure). Anything else, a torn entry too, is false.
23
+ * @param {any} entry @returns {boolean}
24
+ */
25
+ export function filterUnsure(entry: any): boolean;
26
+ /**
27
+ * @param {{text: string, filter?: {priority?: string[], labels?: string[]}}} a `filter` = the job's signed `ticketFilter` (or absent)
28
+ * @returns {{outcome: 'run', unsure?: string}|{outcome: 'skip', reason: string}}
29
+ */
30
+ export function decideTicket({ text, filter }: {
31
+ text: string;
32
+ filter?: {
33
+ priority?: string[];
34
+ labels?: string[];
35
+ };
36
+ }): {
37
+ outcome: "run";
38
+ unsure?: string;
39
+ } | {
40
+ outcome: "skip";
41
+ reason: string;
42
+ };
43
+ /** R9 (9.4): the words for it, one owner (the grid's open row and the badge's title read them). */
44
+ export const FILTER_UNSURE_SAY: "the filter was unsure about this ticket";
@@ -0,0 +1,84 @@
1
+ /**
2
+ * M13 piece 3: the config file a server starts from. An explicit path (a test seam) wins; otherwise the file of the WINNING place for `server` (src/mcp-sources.js,
3
+ * the one decider), or `~/.mcp.json` when no place has it. `remote` true = the winner has no start command (listed, not usable).
4
+ * @param {string} server @param {string} [explicit] @param {string} [home] the config home (tests) @returns {{ file: string, remote: boolean }}
5
+ */
6
+ export function configForServer(server: string, explicit?: string, home?: string): {
7
+ file: string;
8
+ remote: boolean;
9
+ };
10
+ /** the tool and the arguments one read of a list's kind makes @param {'issue'|'pull'} kind @param {string} owner @param {string} repo @param {number} number */
11
+ export function readCall(kind: "issue" | "pull", owner: string, repo: string, number: number): {
12
+ tool: string;
13
+ args: {
14
+ method: string;
15
+ owner: string;
16
+ repo: string;
17
+ pullNumber: number;
18
+ issue_number?: undefined;
19
+ };
20
+ what: string;
21
+ } | {
22
+ tool: string;
23
+ args: {
24
+ method: string;
25
+ owner: string;
26
+ repo: string;
27
+ issue_number: number;
28
+ pullNumber?: undefined;
29
+ };
30
+ what: string;
31
+ };
32
+ /**
33
+ * Read ticket (or pull request) `number` of the list at `listUrl` with the job's `issue_read` (an issues list) or `pull_request_read` (a pulls list).
34
+ * @param {{listUrl: string, number: number, mcp: {server: string, tools: string[]}, configPath?: string, home?: string, timeoutMs?: number}} o
35
+ * @returns {Promise<{ok: true, text: string, url: string, record: {server: string, exposed: string[], missing: Array<{server: string, tool: string}>, calls: Array<Record<string, any>>}} | {ok: false, error: string}>}
36
+ * `record` is what the run keeps (in its `run.json` input entry): what the server exposed and lacked, and each call made.
37
+ */
38
+ export function readTicketMcp({ listUrl, number, mcp, configPath: explicitConfig, home, timeoutMs }: {
39
+ listUrl: string;
40
+ number: number;
41
+ mcp: {
42
+ server: string;
43
+ tools: string[];
44
+ };
45
+ configPath?: string;
46
+ home?: string;
47
+ timeoutMs?: number;
48
+ }): Promise<{
49
+ ok: true;
50
+ text: string;
51
+ url: string;
52
+ record: {
53
+ server: string;
54
+ exposed: string[];
55
+ missing: Array<{
56
+ server: string;
57
+ tool: string;
58
+ }>;
59
+ calls: Array<Record<string, any>>;
60
+ };
61
+ } | {
62
+ ok: false;
63
+ error: string;
64
+ }>;
65
+ /** M13 item 9.5: the only parent env names an MCP gets (plus its own settings); the one list for every place bareloop starts an MCP, so no provider key reaches it */
66
+ export const MCP_PASS_ENV: string[];
67
+ /** how long a bridge waits to start and for one call (ms): the one number for the ticket read and a plan step's bridge */
68
+ export const MCP_TIMEOUT_MS: 90000;
69
+ export function mcpToolName(server: string, tool: string): string;
70
+ export function mcpStartOpts(): {
71
+ passEnv: string[];
72
+ cwd: string;
73
+ };
74
+ export function startRefusal(server: string, e: any): string;
75
+ export function USER_MCP_CONFIG(): string;
76
+ export function remoteRefusal(server: string): string;
77
+ export function firstLine(e: any): string;
78
+ export function isDeviceLogin(text: any): any;
79
+ /**
80
+ * The one tool name a PR read uses. Like `issue_read`, it is the only PR tool name hardcoded: the rest of a job's tools come from the server's own list. The limit, said
81
+ * plainly (ITEM33-BUILD piece 1a, PR-verification job): this is GitHub's own server's spelling, measured against the real server 2026-11-04 (`pull_request_read`, method
82
+ * `get`, args owner/repo/pullNumber); a server that spells it differently is not read, and the person's GitHub server must enable the `pull_requests` toolset.
83
+ */
84
+ export const PR_READ_TOOL: "pull_request_read";
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The ticket numbers this job's runs have read.
3
+ * @param {ReadonlyArray<{job?: string, ticket?: unknown}>} rows the run list's rows @param {string} job @returns {Set<number>}
4
+ */
5
+ export function ranTicketNumbers(rows: ReadonlyArray<{
6
+ job?: string;
7
+ ticket?: unknown;
8
+ }>, job: string): Set<number>;
9
+ /**
10
+ * @param {{job: string, rows: ReadonlyArray<any>, inputs: Array<{value: string}>, mcp: {server: string, tools: string[]}, configPath?: string, look?: typeof lookTickets}} o `look` is a test seam
11
+ * @returns {Promise<{ok: true, number: number} | {ok: false, say: string, nothingNew?: true}>}
12
+ */
13
+ export function newestUnrunTicket({ job, rows, inputs, mcp, configPath, look }: {
14
+ job: string;
15
+ rows: ReadonlyArray<any>;
16
+ inputs: Array<{
17
+ value: string;
18
+ }>;
19
+ mcp: {
20
+ server: string;
21
+ tools: string[];
22
+ };
23
+ configPath?: string;
24
+ look?: typeof lookTickets;
25
+ }): Promise<{
26
+ ok: true;
27
+ number: number;
28
+ } | {
29
+ ok: false;
30
+ say: string;
31
+ nothingNew?: true;
32
+ }>;
33
+ import { lookTickets } from './triggertickets.js';
@@ -0,0 +1,118 @@
1
+ /** the file a ticket line freezes to, relative to the worktree: the label made file-safe, the way a rubric input is named @param {string} label @returns {string} */
2
+ export function ticketInputRel(label: string): string;
3
+ /**
4
+ * The $0 proof of a repo job's ticket line: the job's server is named in the person's MCP config (a file is read; nothing is started), it is not a remote one,
5
+ * and the read tool is among the tools the job signed: `issue_read` for an issues address, `pull_request_read` for a pulls address. The address itself parsed already.
6
+ * @param {{server: string, tools: string[]}} mcp @param {{configPath?: string}} [deps] test seam @param {'issue'|'pull'} [kind]
7
+ * @returns {{ok: true}|{ok: false, error: string}}
8
+ */
9
+ export function proveTicketLine(mcp: {
10
+ server: string;
11
+ tools: string[];
12
+ }, deps?: {
13
+ configPath?: string;
14
+ }, kind?: "issue" | "pull"): {
15
+ ok: true;
16
+ } | {
17
+ ok: false;
18
+ error: string;
19
+ };
20
+ /**
21
+ * The ONE ticket line of a repo job's Inputs: a line 2+ whose value is a GitHub issues or pulls address.
22
+ * @param {{n: number, label: string, value: string}[]} inputs
23
+ * @returns {{ok: true, line: {n: number, label: string, value: string}}|{ok: false, error: string}}
24
+ */
25
+ export function repoTicketLine(inputs: {
26
+ n: number;
27
+ label: string;
28
+ value: string;
29
+ }[]): {
30
+ ok: true;
31
+ line: {
32
+ n: number;
33
+ label: string;
34
+ value: string;
35
+ };
36
+ } | {
37
+ ok: false;
38
+ error: string;
39
+ };
40
+ /**
41
+ * @typedef {object} RepoTicketRecord what the spine's `job-start` keeps of a repo job's ticket: metadata only, never the text
42
+ * @property {string} label @property {string} file the frozen file, relative to the worktree @property {string} url @property {number} number @property {string} title
43
+ * @property {'open'|'closed'|'unknown'} state @property {'mcp'|'page'} source @property {string} sha256 of the masked bytes @property {number} bytes
44
+ * @property {number} masked how many secret shapes were masked (a count, never the values)
45
+ * @property {{server: string, exposed: string[], missing: Array<{server: string, tool: string}>, calls: Array<Record<string, any>>}|null} mcp
46
+ */
47
+ /**
48
+ * RUN START for a repo job that reads a ticket: read the ticket through the MCP, MASK it (before the sha), and write it to `<workdir>/.bareloop-input/<label>.txt`.
49
+ * The folder is hidden through git's private exclude BEFORE the file exists, so the ticket is never a worker write and never in the final commit; it sits inside the
50
+ * worker's readScope, and no write fence can contain it (a signed writeScope is a subfolder of the tracked listing). Nothing is committed and the seed does not move.
51
+ * A refusal is plain words at $0 ("The run did not start. Nothing spent.") and writes nothing.
52
+ * @param {{workdir: string, inputs: {n: number, label: string, value: string}[], ticket: {number: number, mcp: {server: string, tools: string[]}}}} o
53
+ * A PULLS address reads the pull request the same way (`pull_request_read`) and also returns `pr` = `{url, record, reread}` for piece 12's run-start checkout: `record` is the
54
+ * parsed MASKED reply (its `head.sha` is what the worktree is checked out at), `reread` reads it once more if the PR moved while the run was starting.
55
+ * @returns {Promise<{ok: true, ticketText: string, record: RepoTicketRecord, pr?: {url: string, record: any, reread: () => Promise<any>}}|{ok: false, error: string}>}
56
+ */
57
+ export function freezeRepoTicket({ workdir, inputs, ticket }: {
58
+ workdir: string;
59
+ inputs: {
60
+ n: number;
61
+ label: string;
62
+ value: string;
63
+ }[];
64
+ ticket: {
65
+ number: number;
66
+ mcp: {
67
+ server: string;
68
+ tools: string[];
69
+ };
70
+ };
71
+ }): Promise<{
72
+ ok: true;
73
+ ticketText: string;
74
+ record: RepoTicketRecord;
75
+ pr?: {
76
+ url: string;
77
+ record: any;
78
+ reread: () => Promise<any>;
79
+ };
80
+ } | {
81
+ ok: false;
82
+ error: string;
83
+ }>;
84
+ export { TICKET_INPUT_DIR };
85
+ /**
86
+ * what the spine's `job-start` keeps of a repo job's ticket: metadata only, never the text
87
+ */
88
+ export type RepoTicketRecord = {
89
+ label: string;
90
+ /**
91
+ * the frozen file, relative to the worktree
92
+ */
93
+ file: string;
94
+ url: string;
95
+ number: number;
96
+ title: string;
97
+ state: "open" | "closed" | "unknown";
98
+ source: "mcp" | "page";
99
+ /**
100
+ * of the masked bytes
101
+ */
102
+ sha256: string;
103
+ bytes: number;
104
+ /**
105
+ * how many secret shapes were masked (a count, never the values)
106
+ */
107
+ masked: number;
108
+ mcp: {
109
+ server: string;
110
+ exposed: string[];
111
+ missing: Array<{
112
+ server: string;
113
+ tool: string;
114
+ }>;
115
+ calls: Array<Record<string, any>>;
116
+ } | null;
117
+ };
118
+ import { TICKET_INPUT_DIR } from './worktree.js';
@@ -0,0 +1,21 @@
1
+ /**
2
+ * @param {any} spec the signed job @param {{kind: 'new-ticket', input: string}} trigger
3
+ * @returns {{ok: true, listUrl: string, server: string, watch: string[]} | {ok: false, say: string}}
4
+ */
5
+ export function ticketLookOf(spec: any, trigger: {
6
+ kind: "new-ticket";
7
+ input: string;
8
+ }): {
9
+ ok: true;
10
+ listUrl: string;
11
+ server: string;
12
+ watch: string[];
13
+ } | {
14
+ ok: false;
15
+ say: string;
16
+ };
17
+ /**
18
+ * The Inputs labels a job could start a schedule on: only a Tickets MCP job whose signed tools hold `list_issues`, and only its issues-list lines. Empty = the schedule card
19
+ * does not offer "When a new ticket arrives". The card offers these; `ticketLookOf` is still the one judge at sign time. @param {any} spec @returns {string[]}
20
+ */
21
+ export function ticketInputLabels(spec: any): string[];
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The one reader of a ticket list address: its kind (`issue` or `pull`), owner and repo and the address of one ticket on it, or the one refusal every caller shows.
3
+ * A pull address is `/pull/<n>` (GitHub's own spelling), an issue address `/issues/<n>`.
4
+ * @param {unknown} listUrl @returns {{ok: true, kind: 'issue'|'pull', owner: string, repo: string, ticketUrl: (number: number) => string} | {ok: false, error: string}}
5
+ */
6
+ export function parseTicketList(listUrl: unknown): {
7
+ ok: true;
8
+ kind: "issue" | "pull";
9
+ owner: string;
10
+ repo: string;
11
+ ticketUrl: (number: number) => string;
12
+ } | {
13
+ ok: false;
14
+ error: string;
15
+ };
16
+ /** The ISSUE lists a signed job names (the new-ticket look reads these with `list_issues`; a pulls list is not one): role -> address, for every page input whose address has the issues-list shape. @param {{sources?: Array<{role: string, kind?: string, path: string}>}} arbiter @returns {Record<string, string>} */
17
+ export function ticketListsOf(arbiter: {
18
+ sources?: Array<{
19
+ role: string;
20
+ kind?: string;
21
+ path: string;
22
+ }>;
23
+ }): Record<string, string>;
24
+ /**
25
+ * The ONE reader of a typed ticket number (the CLI's `--ticket` and the panel's Ticket box): a whole number written in digits, no sign, no zero in front, at most 10 digits.
26
+ * @param {unknown} text @returns {number|undefined} the number, or undefined when the text is not one
27
+ */
28
+ export function ticketNumberOf(text: unknown): number | undefined;
29
+ /** The fields a signed schedule may watch (item 7): typed values the list already carries. */
30
+ export const WATCHABLE: readonly string[];
31
+ /** the shape of a ticket list address: owner and repo are the first two groups; the third is `issues` (a ticket list) or `pulls` (a pull request list, MCP PR reader) */
32
+ export const LIST_URL: RegExp;
33
+ /** M13 piece 7 (9.7): the one cap on a ticket number, 10 digits. Every door that takes or reads a ticket number uses `isTicketNumber`. Under 2^53, so a safe JS number. */
34
+ export const TICKET_MAX: 9999999999;
35
+ export function isTicketNumber(n: unknown): n is number;
36
+ /** The words every refusal of a ticket number uses. */
37
+ export const TICKET_NUMBER_WORDS: string;
package/types/tools.d.ts CHANGED
@@ -265,6 +265,7 @@ export const TOOL_BY_VERB: Readonly<{
265
265
  }>;
266
266
  export const ISOLATE_MAX_BYTES: 65536;
267
267
  export const CTX_TOOLS: readonly string[];
268
+ export function mcpStrategy(names: string[]): string;
268
269
  export const COMPONENT_STRATEGIES: Readonly<{
269
270
  select: string;
270
271
  compress: string;
@@ -12,10 +12,11 @@ export function validateTrigger(t: unknown): {
12
12
  code: "invalid-value" | "unknown-field";
13
13
  path: string;
14
14
  };
15
- /** @typedef {import('./triggerclock.js').Schedule | {kind:'new-file', folder:string} | {kind:'file-updated', path:string}} Trigger */
15
+ /** @typedef {import('./triggerclock.js').Schedule | {kind:'new-file', folder:string} | {kind:'file-updated', path:string} | {kind:'new-ticket', input:string}} Trigger */
16
16
  export const TRIGGER_KINDS: readonly string[];
17
17
  export const CLOCK_KINDS: readonly string[];
18
18
  export const FILE_KINDS: readonly string[];
19
+ export const TICKET_KINDS: readonly string[];
19
20
  export function isClockTrigger(t: unknown): t is {
20
21
  kind: "daily" | "weekdays" | "weekly";
21
22
  hour: number;
@@ -28,10 +29,17 @@ export function isFileTrigger(t: unknown): t is {
28
29
  kind: "file-updated";
29
30
  path: string;
30
31
  };
32
+ export function isTicketTrigger(t: unknown): t is {
33
+ kind: "new-ticket";
34
+ input: string;
35
+ };
31
36
  export type Trigger = import("./triggerclock.js").Schedule | {
32
37
  kind: "new-file";
33
38
  folder: string;
34
39
  } | {
35
40
  kind: "file-updated";
36
41
  path: string;
42
+ } | {
43
+ kind: "new-ticket";
44
+ input: string;
37
45
  };
@@ -20,8 +20,12 @@ export function due(schedule: Schedule, rows: ClockRow[], now: number): Due;
20
20
  * @returns {number}
21
21
  */
22
22
  export function nextSlot(schedule: Schedule, afterMs: number): number;
23
- /** The trigger was set at `now` under signature `sig`: no slot before this ever fires. @param {string} file @param {number} now @param {string} sig */
24
- export function armTrigger(file: string, now: number, sig: string): void;
23
+ /**
24
+ * The trigger was set at `now` under signature `sig`: no slot before this ever fires. `ticketN` (a ticket schedule turned on by its first green run, R7) = the ticket number that run
25
+ * read: the first look baselines only tickets up to it.
26
+ * @param {string} file @param {number} now @param {string} sig @param {number} [ticketN]
27
+ */
28
+ export function armTrigger(file: string, now: number, sig: string, ticketN?: number): void;
25
29
  /**
26
30
  * Record that the run for this due slot is starting (the consuming row). Write-once per slot.
27
31
  * @param {string} file @param {Due} d the result of `due` with fire true @param {number} now @param {string} sig
@@ -1,5 +1,13 @@
1
- /** The file-kind rows of the job's ledger that still count (a released `ran` does not). @param {string} file @returns {SeenRow[]} */
2
- export function readSeen(file: string): SeenRow[];
1
+ /**
2
+ * The seen-kind rows of the job's ledger that still count (a released `ran` does not). `sig` (the ticket look only) = just the rows of that signing; absent = every row.
3
+ * @param {string} file @param {string} [sig] @returns {SeenRow[]}
4
+ */
5
+ export function readSeen(file: string, sig?: string): SeenRow[];
6
+ /**
7
+ * The ONE appender here: write-once by live id (a second row with the same id is not written). With `sig` (the ticket look) the id is unique within that signing and the row is stamped with it.
8
+ * @param {string} file @param {SeenRow} row @param {string} [sig] @returns {boolean} written
9
+ */
10
+ export function appendSeen(file: string, row: SeenRow, sig?: string): boolean;
3
11
  /** Arrived rows are never overwritten: the 2nd arrival of a sha (after a drop) gets its own id. @param {string} ledger @param {ToRun & {name?:string}} item @param {number} at the scheduler's clock, never the file's mtime @param {string} sig */
4
12
  export function recordArrived(ledger: string, item: ToRun & {
5
13
  name?: string;
@@ -12,7 +20,7 @@ export function recordDropped(ledger: string, item: {
12
20
  id?: string;
13
21
  }, why: string, at: number, sig: string): boolean;
14
22
  /**
15
- * The queue: arrived and neither ran nor dropped, oldest arrival first. Identical arrival times: by name, then by sha (deterministic).
23
+ * The queue: arrived and neither ran nor dropped, oldest arrival first. Identical arrival times: by name (numbers as numbers, `#9` before `#10`), then by sha (deterministic).
16
24
  * @param {SeenRow[]} rows @returns {(SeenRow & {path:string})[]}
17
25
  */
18
26
  export function queueOf(rows: SeenRow[]): (SeenRow & {
@@ -60,7 +68,7 @@ export function createFileTrigger({ mode, target, ledger, sig, now }: {
60
68
  refused: Refused[];
61
69
  };
62
70
  };
63
- /** @typedef {{id:string, kind:'baseline'|'arrived'|'ran'|'dropped', sha:string, name:string, size:number, at:number, sig?:string, path?:string, why?:string, of?:string}} SeenRow */
71
+ /** @typedef {{id:string, kind:'baseline'|'arrived'|'ran'|'dropped'|'unreadable'|'looked', sha:string, name:string, size:number, at:number, sig?:string, path?:string, why?:string, of?:string}} SeenRow */
64
72
  /** @typedef {{path:string, sha:string, size:number}} ToRun */
65
73
  /** @typedef {{path:string, why:string}} Refused */
66
74
  /** Consecutive polls with the same size and mtime before a file is taken. (Two matches in a row = taken on the third sighting.) */
@@ -72,7 +80,7 @@ export function recordRan(ledger: string, item: {
72
80
  }, at: number, sig: string): boolean;
73
81
  export type SeenRow = {
74
82
  id: string;
75
- kind: "baseline" | "arrived" | "ran" | "dropped";
83
+ kind: "baseline" | "arrived" | "ran" | "dropped" | "unreadable" | "looked";
76
84
  sha: string;
77
85
  name: string;
78
86
  size: number;