@bussolabs/closeyourit-cli 0.15.0 → 0.17.0

package/README.md

@@ -105,6 +105,9 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `tickets watch\|unwatch <id> --project <id\|key>` | Watch / stop watching a ticket (its notifications). |
 | `tickets branch <id\|code> --project <id\|key>` | Create a GitHub branch from a ticket (name prefixed with the ticket code). |
 | `tickets pr <id\|code> --project <id\|key>` | Open a GitHub pull request from a ticket (head = the ticket branch). |
+| `tickets lease claim <id\|code> --project <id\|key> [--ttl <seconds>] [--run-id <id>]` | Claim the working lease on a ticket (server default TTL: 8h). Exits non-zero on a 409, naming the current holder and its expiry. |
+| `tickets lease renew <id\|code> --project <id\|key> [--ttl <seconds>] [--run-id <id>]` | Extend your own lease before it expires. |
+| `tickets lease release <id\|code> --project <id\|key> [--run-id <id>]` | Release your own lease so someone else can claim the ticket. |
 | `ideas delete <id> --project <id\|key> --confirm` | Delete an idea (author always allowed; others need ideas.delete). |
 | `ideas archive\|unarchive <id> --project <id\|key>` | Archive an idea (open → archived) / reopen it. |
 | `ideas case-update <idea-id> <case-id> --project <id\|key> [--title] [--description]` | Update a case (example) of an idea. |
@@ -115,11 +118,12 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `logs show <id>` | Show a single log entry (attributes, trace id, correlation). |
 | `logs link <id> --to <Errors::Group:uuid\|Ticketing::Ticket:uuid>` | Manually link a log entry to an error group or ticket. |
 | `logs unlink <id> <link-id> --confirm` | Remove a manual log link. |
-| `kb list [--project <id\|key>] [--kind] [--per] [--page]` | List knowledge pages. Cross-project: omit `--project` for every visible project. |
+| `kb list [--project <id\|key>] [--kind] [--status] [--awaiting-consolidation] [--per] [--page]` | List knowledge pages. Cross-project: omit `--project` for every visible project. Published only unless `--status` says otherwise. |
 | `kb search <query…> [--project <id\|key>] [--kind] [--per] [--page] [--with-related]` | Search knowledge pages (semantic when available, title ILIKE fallback). |
 | `kb show <id> [--related] [--question <q>]` | Show one knowledge page: metadata header, raw markdown body, then the technical section. |
 | `kb related <id> [--question <q>] [--links-only]` | Pages to read next: linked with `[[wiki links]]` plus close matches by meaning. |
-| `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>]` | Create a knowledge page (optional technical section, kept separate from the body). |
+| `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>]` | Create a knowledge page (optional technical section, kept separate from the body). With `--in-review` the page waits for a human and stays out of search, answers and related panels. |
+| `kb consolidate <id> --path <doc-path>` | Mark an accepted page as written to the versioned docs, recording where the document lives. |
 | `kb update <id> [--title] [--kind] [--body \| --body-file] [--tech-spec \| --tech-spec-file]` | Update a page (unpassed fields keep their current value). |
 | `kb delete <id> --confirm` | Delete a knowledge page (irreversible). |
 | `kb ask <question…>` | Ask a question; the AI answers from the knowledge base and cites the pages it used. |

package/dist/commands/kb/consolidate.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../base';
+/**
+ * Second step of the review flow: the accepted page has also been written as a versioned document
+ * in the knowledge-base repo, so record where it lives. Accepting and discarding stay human gestures
+ * on the web review page — this command only closes the loop the CLI can close by itself.
+ */
+export default class KbConsolidate extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        path: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/consolidate.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const output_1 = require("../../lib/output");
+/**
+ * Second step of the review flow: the accepted page has also been written as a versioned document
+ * in the knowledge-base repo, so record where it lives. Accepting and discarding stay human gestures
+ * on the web review page — this command only closes the loop the CLI can close by itself.
+ */
+class KbConsolidate extends base_1.BaseCommand {
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static description = 'Mark an accepted page as written to the versioned docs, recording its path';
+    static examples = [
+        '<%= config.bin %> kb consolidate <page-id> --path troubleshooting/rails.md',
+        '<%= config.bin %> kb consolidate <page-id> --path global/git.md --json',
+    ];
+    static flags = {
+        path: core_1.Flags.string({ description: 'Path of the document inside the knowledge-base repo', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbConsolidate);
+        const res = await this.api.post(`/cli/v1/knowledge/pages/${args.id}/consolidated`, { source_path: flags.path });
+        if (!this.jsonEnabled()) {
+            this.log('Knowledge page filed:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbConsolidate;

package/dist/commands/kb/create.d.ts

@@ -9,6 +9,8 @@ export default class KbCreate extends BaseCommand {
         'body-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'tech-spec': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'tech-spec-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'in-review': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'review-note': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<unknown>;

package/dist/commands/kb/create.js

@@ -10,6 +10,7 @@ class KbCreate extends base_1.BaseCommand {
         '<%= config.bin %> kb create --project acme-api --title "Kamal rollback" --body "Steps…"',
         '<%= config.bin %> kb create -p acme-api --title "ADR: queue backend" --kind decision --body-file ./adr.md',
         '<%= config.bin %> kb create -p acme-api --title "Deploy" --body-file ./body.md --tech-spec-file ./tech.md',
+        '<%= config.bin %> kb create -p acme-api --title "Worktree trap" --body-file ./note.md --in-review --review-note "Hit it today, not obvious from the code"',
     ];
     static flags = {
         // Required — passed straight to the server as `project` (key or UUID), resolved there.
@@ -20,6 +21,10 @@ class KbCreate extends base_1.BaseCommand {
         'body-file': core_1.Flags.string({ description: 'Read the body (markdown) from a local file' }),
         'tech-spec': core_1.Flags.string({ description: 'Technical section, kept separate from the simple body' }),
         'tech-spec-file': core_1.Flags.string({ description: 'Read the technical section from a local file' }),
+        // Propose instead of publish: the page waits for a human in the review queue and stays out of
+        // search, answers and related panels until it is accepted (see `kb list --status in_review`).
+        'in-review': core_1.Flags.boolean({ description: 'Create the page in review instead of publishing it' }),
+        'review-note': core_1.Flags.string({ description: 'One line explaining why the page is worth keeping (review queue)' }),
     };
     async run() {
         const { flags } = await this.parse(KbCreate);
@@ -44,15 +49,20 @@ class KbCreate extends base_1.BaseCommand {
                 this.error(`File not found or unreadable: ${flags['tech-spec-file']}`, { exit: 2 });
             }
         }
+        if (flags['review-note'] !== undefined && !flags['in-review']) {
+            this.error('--review-note only applies to a page created with --in-review.', { exit: 2 });
+        }
         const res = await this.api.post('/cli/v1/knowledge/pages', {
             project: flags.project,
             title: flags.title,
             kind: flags.kind,
             body,
             tech_spec: techSpec,
+            in_review: flags['in-review'] ? true : undefined,
+            review_note: flags['review-note'],
         });
         if (!this.jsonEnabled()) {
-            this.log('Knowledge page created:');
+            this.log(flags['in-review'] ? 'Knowledge page proposed, waiting for review:' : 'Knowledge page created:');
             this.log((0, output_1.renderRecord)(res.data ?? {}));
         }
         return res;

package/dist/commands/kb/list.d.ts

@@ -6,6 +6,8 @@ export default class KbList extends BaseCommand {
         page: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
         project: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         kind: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'awaiting-consolidation': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         per: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<unknown>;

package/dist/commands/kb/list.js

@@ -9,21 +9,31 @@ class KbList extends base_1.BaseCommand {
         '<%= config.bin %> kb list',
         '<%= config.bin %> kb list --project acme-api --kind decision',
         '<%= config.bin %> kb list --kind note,guide --per 50 --json',
+        '<%= config.bin %> kb list --status in_review',
+        '<%= config.bin %> kb list --awaiting-consolidation',
     ];
     static flags = {
         // Optional (the endpoint is cross-project): omit it to span every visible project.
         project: core_1.Flags.string({ char: 'p', description: 'Filter by project (key or UUID)' }),
         kind: core_1.Flags.string({ description: 'Filter by kind: note|decision|guide (repeatable or comma-separated)', multiple: true }),
+        // Without it the server lists published pages only: proposals waiting for review never show up
+        // in an ordinary listing.
+        status: core_1.Flags.string({ description: 'Filter by review state', options: [...knowledge_1.KNOWLEDGE_STATUSES] }),
+        'awaiting-consolidation': core_1.Flags.boolean({
+            description: 'Only accepted pages not yet written to the versioned docs',
+        }),
         per: core_1.Flags.integer({ description: 'Page size' }),
         ...base_1.pageFlag,
     };
     async run() {
         const { flags } = await this.parse(KbList);
         const query = (0, knowledge_1.buildPagesQuery)({
+            awaitingConsolidation: flags['awaiting-consolidation'],
             kinds: (0, knowledge_1.normalizeKinds)(flags.kind),
             page: flags.page,
             per: flags.per,
             project: flags.project,
+            status: flags.status,
         });
         const res = await this.api.get(`/cli/v1/knowledge/pages?${query}`);
         if (!this.jsonEnabled()) {

package/dist/commands/tickets/lease/claim.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base';
+export default class TicketsLeaseClaim extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        ttl: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/tickets/lease/claim.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseClaim extends base_1.BaseCommand {
+    static description = 'Claim the working lease on a ticket, so nobody else (person or agent) starts it at the same time';
+    static examples = [
+        '<%= config.bin %> tickets lease claim <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease claim DRFL-3 -p driverone-flutter --ttl 3600 --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        ttl: core_1.Flags.integer({ description: 'Lease duration in seconds (server default: 8h; range 1s..30 days)' }),
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseClaim);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags.ttl !== undefined)
+            body.ttl_seconds = flags.ttl;
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.post(path, body);
+        }
+        catch (error) {
+            // 409 = somebody else already holds it. --json prints the full backend envelope (details
+            // included) itself and returns, so BaseCommand.catch never trims it down to {code,message};
+            // human mode gets the holder spelled out in the message instead (requisito CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            const lease = res.data ?? {};
+            this.log(`Ticket ${args.id} leased until ${lease.expires_at ?? '?'}:`);
+            this.log((0, output_1.renderRecord)(leaseSummary(lease)));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseClaim;
+/** Flatten the lease payload for `renderRecord`: `held_by` is a nested object, so print it as one line. */
+function leaseSummary(lease) {
+    const heldBy = lease.held_by;
+    return {
+        ticket: lease.ticket,
+        run_id: lease.run_id,
+        held_by: heldBy ? `${heldBy.kind} ${heldBy.name ?? heldBy.id}` : null,
+        expires_at: lease.expires_at,
+        host_id: lease.host_id,
+        account_id: lease.account_id,
+        agent: lease.agent,
+        execution_phase: lease.execution_phase,
+        profile_digest: lease.profile_digest,
+    };
+}

package/dist/commands/tickets/lease/release.d.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../../base';
+export default class TicketsLeaseRelease extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/tickets/lease/release.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseRelease extends base_1.BaseCommand {
+    static description = 'Release your own working lease on a ticket, so someone else can claim it';
+    static examples = [
+        '<%= config.bin %> tickets lease release <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease release DRFL-3 -p driverone-flutter --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseRelease);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.delete(path, { body });
+        }
+        catch (error) {
+            // 409 = somebody else already holds it, 404 = no lease to release. --json prints the full
+            // backend envelope (details included) itself and returns, so BaseCommand.catch never trims
+            // it down to {code,message}; human mode gets the holder spelled out instead (CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            this.log(`Ticket ${args.id} lease released:`);
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseRelease;

package/dist/commands/tickets/lease/renew.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base';
+export default class TicketsLeaseRenew extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        ttl: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/tickets/lease/renew.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseRenew extends base_1.BaseCommand {
+    static description = 'Extend your own working lease on a ticket before it expires';
+    static examples = [
+        '<%= config.bin %> tickets lease renew <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease renew DRFL-3 -p driverone-flutter --ttl 3600 --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        ttl: core_1.Flags.integer({ description: 'New lease duration in seconds (server default: 8h; range 1s..30 days)' }),
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseRenew);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags.ttl !== undefined)
+            body.ttl_seconds = flags.ttl;
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.put(path, body);
+        }
+        catch (error) {
+            // 409 = somebody else already holds it, 404 = no lease to renew. --json prints the full
+            // backend envelope (details included) itself and returns, so BaseCommand.catch never trims
+            // it down to {code,message}; human mode gets the holder spelled out instead (CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            const lease = res.data ?? {};
+            this.log(`Ticket ${args.id} lease renewed until ${lease.expires_at ?? '?'}:`);
+            this.log((0, output_1.renderRecord)(leaseSummary(lease)));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseRenew;
+/** Flatten the lease payload for `renderRecord`: `held_by` is a nested object, so print it as one line. */
+function leaseSummary(lease) {
+    const heldBy = lease.held_by;
+    return {
+        ticket: lease.ticket,
+        run_id: lease.run_id,
+        held_by: heldBy ? `${heldBy.kind} ${heldBy.name ?? heldBy.id}` : null,
+        expires_at: lease.expires_at,
+        host_id: lease.host_id,
+        account_id: lease.account_id,
+        agent: lease.agent,
+        execution_phase: lease.execution_phase,
+        profile_digest: lease.profile_digest,
+    };
+}

package/dist/lib/knowledge.d.ts

@@ -7,9 +7,15 @@ export declare const KNOWLEDGE_KINDS: readonly ["note", "decision", "guide"];
 export declare function normalizeKinds(values?: string[]): string[];
 /** Collapse whitespace and truncate a cell so the list table stays single-line. */
 export declare function truncate(value: string, max?: number): string;
+/**
+ * Review states a page can be filtered by (Knowledge::Page#status). `all` drops the filter;
+ * omitting `--status` leaves the server default, which is `published` — so an ordinary `kb list`
+ * never shows proposals waiting for review.
+ */
+export declare const KNOWLEDGE_STATUSES: readonly ["published", "in_review", "rejected", "all"];
 /**
  * Build the shared query string for `kb list` / `kb search`. Kinds go out as the
- * `kind[]` array param; `page` is always sent, `per`/`project`/`q` only when set.
+ * `kind[]` array param; `page` is always sent, the rest only when set.
  */
 export declare function buildPagesQuery(opts: {
     kinds: string[];
@@ -18,6 +24,8 @@ export declare function buildPagesQuery(opts: {
     project?: string;
     q?: string;
     related?: boolean;
+    status?: string;
+    awaitingConsolidation?: boolean;
 }): string;
 /** A related-page row as returned by the server (KnowledgeRelatedPageSerializer). */
 export interface RelatedRow extends Record<string, unknown> {
@@ -40,5 +48,11 @@ export declare function renderRelated(rows: RelatedRow[], heading?: string, inde
  * order as the table above it. Results without related pages are simply left out.
  */
 export declare function renderRelatedGroups(pages: Array<Record<string, unknown>>, grouped: Record<string, RelatedRow[]>): string;
-/** Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED. */
+/**
+ * Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED.
+ *
+ * STATUS shows up only when a row is not `published` — an ordinary listing already contains
+ * nothing but published pages, so the extra column would be noise; the review queue, where the
+ * state is the whole point, gets it automatically.
+ */
 export declare function renderPagesTable(pages: Array<Record<string, unknown>>): string;

package/dist/lib/knowledge.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWLEDGE_KINDS = void 0;
+exports.KNOWLEDGE_STATUSES = exports.KNOWLEDGE_KINDS = void 0;
 exports.normalizeKinds = normalizeKinds;
 exports.truncate = truncate;
 exports.buildPagesQuery = buildPagesQuery;
@@ -27,9 +27,15 @@ function truncate(value, max = 60) {
     const flat = value.replace(/\s+/g, ' ').trim();
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
+/**
+ * Review states a page can be filtered by (Knowledge::Page#status). `all` drops the filter;
+ * omitting `--status` leaves the server default, which is `published` — so an ordinary `kb list`
+ * never shows proposals waiting for review.
+ */
+exports.KNOWLEDGE_STATUSES = ['published', 'in_review', 'rejected', 'all'];
 /**
  * Build the shared query string for `kb list` / `kb search`. Kinds go out as the
- * `kind[]` array param; `page` is always sent, `per`/`project`/`q` only when set.
+ * `kind[]` array param; `page` is always sent, the rest only when set.
  */
 function buildPagesQuery(opts) {
     const query = new URLSearchParams();
@@ -44,6 +50,10 @@ function buildPagesQuery(opts) {
         query.set('q', opts.q);
     if (opts.related)
         query.set('related', '1');
+    if (opts.status)
+        query.set('status', opts.status);
+    if (opts.awaitingConsolidation)
+        query.set('awaiting_consolidation', '1');
     return query.toString();
 }
 /**
@@ -72,13 +82,23 @@ function renderRelatedGroups(pages, grouped) {
         .map(({ rows, title }) => renderRelated(rows, `  ${(0, output_1.sanitize)(title)}`, '    '));
     return blocks.length === 0 ? '' : ['\n🔗 Related:', ...blocks].join('\n');
 }
-/** Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED. */
+/**
+ * Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED.
+ *
+ * STATUS shows up only when a row is not `published` — an ordinary listing already contains
+ * nothing but published pages, so the extra column would be noise; the review queue, where the
+ * state is the whole point, gets it automatically.
+ */
 function renderPagesTable(pages) {
-    return (0, output_1.renderTable)(['TITLE', 'KIND', 'PROJECT', 'AUTHOR', 'UPDATED'], pages.map((page) => [
-        truncate(String(page.title ?? '')),
-        String(page.kind ?? ''),
-        String(page.project ?? ''),
-        String(page.author ?? ''),
-        String(page.updated_at ?? ''),
-    ]));
+    const showStatus = pages.some((page) => page.status !== undefined && page.status !== 'published');
+    const headers = showStatus
+        ? ['TITLE', 'KIND', 'STATUS', 'PROJECT', 'AUTHOR', 'UPDATED']
+        : ['TITLE', 'KIND', 'PROJECT', 'AUTHOR', 'UPDATED'];
+    return (0, output_1.renderTable)(headers, pages.map((page) => {
+        const row = [truncate(String(page.title ?? '')), String(page.kind ?? '')];
+        if (showStatus)
+            row.push(String(page.status ?? ''));
+        row.push(String(page.project ?? ''), String(page.author ?? ''), String(page.updated_at ?? ''));
+        return row;
+    }));
 }

package/dist/lib/lease.d.ts

@@ -0,0 +1,44 @@
+/**
+ * On a 409 lease conflict, rewrite the error message to name who holds the ticket and until when.
+ * An automation reading "R409-LEASE-001: Ticket is already leased" alone cannot decide whether to
+ * skip to the next ticket — it needs the holder. Every other status/code (and a 409 without the
+ * expected `details.holder` shape) passes through untouched, so unrelated errors keep the server's
+ * own wording. Human-mode only: `--json` prints its own full envelope instead (see
+ * `leaseErrorEnvelope`), so it never goes through this rewrite.
+ */
+export declare function describeLeaseConflict(error: unknown): unknown;
+/** Allow-listed `details` for the --json envelope: only the fields a lease conflict is documented to carry. */
+interface LeaseErrorDetails {
+    holder: {
+        held_by: {
+            kind: string;
+            id: string;
+            name?: string;
+        };
+        expires_at?: string;
+    };
+}
+/**
+ * Full `{error:{code,message,details}}` envelope for a lease command failure in `--json` mode.
+ * `BaseCommand.catch` — shared by every command in the CLI — only ever emits `{code,message}`; a
+ * script reading `--json` on a 409 needs `details.holder` too (who holds the ticket, until when),
+ * so lease commands print this themselves and return before the error reaches `catch()`, instead of
+ * changing that shared, cross-cutting behaviour (out of scope for CYCL-14).
+ *
+ * `details` is rebuilt field-by-field from an explicit allow-list (`holder.held_by.{kind,id,name}`,
+ * `holder.expires_at`) instead of forwarding `error.details` verbatim — same reasoning as
+ * `BaseCommand.catch`'s own allow-listed envelope (see `base.ts`): never serialize a server-shaped
+ * object of arbitrary provenance straight into `--json` output. Any other field the backend happens
+ * to send inside `details` (e.g. a stray `holder.ticket`) is dropped, not forwarded.
+ *
+ * Returns undefined for anything that isn't an `ApiRequestError`: callers should let those propagate
+ * to `catch()` as usual.
+ */
+export declare function leaseErrorEnvelope(error: unknown): {
+    error: {
+        code: string;
+        message: string;
+        details?: LeaseErrorDetails;
+    };
+} | undefined;
+export {};

package/dist/lib/lease.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeLeaseConflict = describeLeaseConflict;
+exports.leaseErrorEnvelope = leaseErrorEnvelope;
+const api_1 = require("./api");
+/** Extract `{kind,id,name?,expiresAt?}` from a 409's `details`, or undefined if the shape doesn't match. */
+function parseLeaseHolder(details) {
+    const holder = details?.holder;
+    const heldBy = holder?.held_by;
+    if (!heldBy?.kind || !heldBy.id)
+        return undefined;
+    return { kind: heldBy.kind, id: heldBy.id, name: heldBy.name, expiresAt: holder?.expires_at };
+}
+/**
+ * On a 409 lease conflict, rewrite the error message to name who holds the ticket and until when.
+ * An automation reading "R409-LEASE-001: Ticket is already leased" alone cannot decide whether to
+ * skip to the next ticket — it needs the holder. Every other status/code (and a 409 without the
+ * expected `details.holder` shape) passes through untouched, so unrelated errors keep the server's
+ * own wording. Human-mode only: `--json` prints its own full envelope instead (see
+ * `leaseErrorEnvelope`), so it never goes through this rewrite.
+ */
+function describeLeaseConflict(error) {
+    if (!(error instanceof api_1.ApiRequestError) || error.status !== 409)
+        return error;
+    const holder = parseLeaseHolder(error.details);
+    if (!holder)
+        return error;
+    const who = holder.name ? `${holder.kind} "${holder.name}"` : `${holder.kind} ${holder.id}`;
+    const until = holder.expiresAt ? ` until ${holder.expiresAt}` : '';
+    return new api_1.ApiRequestError(error.status, error.code, `Ticket already leased by ${who}${until}.`, error.details);
+}
+/**
+ * Full `{error:{code,message,details}}` envelope for a lease command failure in `--json` mode.
+ * `BaseCommand.catch` — shared by every command in the CLI — only ever emits `{code,message}`; a
+ * script reading `--json` on a 409 needs `details.holder` too (who holds the ticket, until when),
+ * so lease commands print this themselves and return before the error reaches `catch()`, instead of
+ * changing that shared, cross-cutting behaviour (out of scope for CYCL-14).
+ *
+ * `details` is rebuilt field-by-field from an explicit allow-list (`holder.held_by.{kind,id,name}`,
+ * `holder.expires_at`) instead of forwarding `error.details` verbatim — same reasoning as
+ * `BaseCommand.catch`'s own allow-listed envelope (see `base.ts`): never serialize a server-shaped
+ * object of arbitrary provenance straight into `--json` output. Any other field the backend happens
+ * to send inside `details` (e.g. a stray `holder.ticket`) is dropped, not forwarded.
+ *
+ * Returns undefined for anything that isn't an `ApiRequestError`: callers should let those propagate
+ * to `catch()` as usual.
+ */
+function leaseErrorEnvelope(error) {
+    if (!(error instanceof api_1.ApiRequestError))
+        return undefined;
+    const holder = parseLeaseHolder(error.details);
+    const details = holder
+        ? {
+            holder: {
+                held_by: holder.name ? { kind: holder.kind, id: holder.id, name: holder.name } : { kind: holder.kind, id: holder.id },
+                ...(holder.expiresAt ? { expires_at: holder.expiresAt } : {}),
+            },
+        }
+        : undefined;
+    return { error: { code: error.code, message: error.message, details } };
+}