feat(loop): inject a .qwen/loop.md task file at fire time via sentinels

packages/cli/src/acp-integration/session/Session.test.ts

@@ -4256,6 +4256,134 @@ describe('Session', () => {
         });
       });
 
+      it('expands a loop.md sentinel into the task block and echoes a clean label', async () => {
+        const tmpDir = await fs.mkdtemp(
+          path.join(os.tmpdir(), 'loop-md-session-'),
+        );
+        const loopMdPath = path.join(tmpDir, '.qwen', 'loop.md');
+        await fs.mkdir(path.dirname(loopMdPath), { recursive: true });
+        await fs.writeFile(loopMdPath, '- finish the migration');
+        mockConfig.getWorkingDir = vi.fn().mockReturnValue(tmpDir);
+
+        const scheduler = {
+          size: 1,
+          hasPendingWork: true,
+          start: vi.fn(
+            (
+              callback: (job: { prompt: string; cronExpr?: string }) => void,
+            ) => {
+              callback({
+                prompt: '<<loop.md-dynamic>>',
+                cronExpr: '@wakeup',
+              });
+            },
+          ),
+          stop: vi.fn(),
+          getExitSummary: vi.fn().mockReturnValue(undefined),
+        };
+        mockConfig.isCronEnabled = vi.fn().mockReturnValue(true);
+        mockConfig.getCronScheduler = vi.fn().mockReturnValue(scheduler);
+        mockChat.sendMessageStream = vi
+          .fn()
+          .mockResolvedValueOnce(createEmptyStream())
+          .mockResolvedValueOnce(createEmptyStream());
+
+        try {
+          await session.prompt({
+            sessionId: 'test-session-id',
+            prompt: [{ type: 'text', text: 'hello' }],
+          });
+
+          // The client sees a stable label, never the raw sentinel.
+          await vi.waitFor(() => {
+            expect(mockClient.sessionUpdate).toHaveBeenCalledWith({
+              sessionId: 'test-session-id',
+              update: {
+                sessionUpdate: 'user_message_chunk',
+                content: {
+                  type: 'text',
+                  text: `Loop tick — tasks from ${loopMdPath}`,
+                },
+                _meta: { source: 'loop' },
+              },
+            });
+          });
+
+          // The model receives the expanded full task block, not the sentinel.
+          let block = '';
+          await vi.waitFor(() => {
+            const cronCall = (
+              mockChat.sendMessageStream as ReturnType<typeof vi.fn>
+            ).mock.calls.find(
+              (c) =>
+                Array.isArray(c[1]?.message) &&
+                c[1].message.some((p: { text?: string }) =>
+                  p.text?.includes('finish the migration'),
+                ),
+            );
+            expect(cronCall).toBeDefined();
+            block = (cronCall![1].message as Array<{ text?: string }>)
+              .map((p) => p.text ?? '')
+              .join('');
+          });
+          expect(block).toContain('# /loop tick — tasks from');
+          expect(block).toContain('- finish the migration');
+        } finally {
+          await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+      });
+
+      it('leaves a non-sentinel cron prompt untouched (no loop.md expansion)', async () => {
+        const scheduler = {
+          size: 1,
+          hasPendingWork: true,
+          start: vi.fn(
+            (
+              callback: (job: { prompt: string; cronExpr?: string }) => void,
+            ) => {
+              callback({
+                prompt: 'do the normal cron thing',
+                cronExpr: '0 * * * *',
+              });
+            },
+          ),
+          stop: vi.fn(),
+          getExitSummary: vi.fn().mockReturnValue(undefined),
+        };
+        mockConfig.isCronEnabled = vi.fn().mockReturnValue(true);
+        mockConfig.getCronScheduler = vi.fn().mockReturnValue(scheduler);
+        mockChat.sendMessageStream = vi
+          .fn()
+          .mockResolvedValueOnce(createEmptyStream())
+          .mockResolvedValueOnce(createEmptyStream());
+
+        await session.prompt({
+          sessionId: 'test-session-id',
+          prompt: [{ type: 'text', text: 'hello' }],
+        });
+
+        await vi.waitFor(() => {
+          expect(mockClient.sessionUpdate).toHaveBeenCalledWith({
+            sessionId: 'test-session-id',
+            update: {
+              sessionUpdate: 'user_message_chunk',
+              content: { type: 'text', text: 'do the normal cron thing' },
+              _meta: { source: 'cron' },
+            },
+          });
+        });
+
+        const sentToModel = () =>
+          (mockChat.sendMessageStream as ReturnType<typeof vi.fn>).mock.calls
+            .flatMap((c) => (Array.isArray(c[1]?.message) ? c[1].message : []))
+            .map((p: { text?: string }) => p.text ?? '')
+            .join('');
+        await vi.waitFor(() => {
+          expect(sentToModel()).toContain('do the normal cron thing');
+        });
+        expect(sentToModel()).not.toContain('# /loop tick');
+      });
+
       it('stops cron-fired ACP prompt before sending when the session token limit is exceeded', async () => {
         let cronCallback: ((job: { prompt: string }) => void) | undefined;
         const scheduler = {

packages/cli/src/acp-integration/session/Session.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import * as os from 'node:os';
 import type {
   Content,
   FunctionCall,
@@ -33,6 +34,8 @@ import {
   AuthType,
   ApprovalMode,
   CompressionStatus,
+  detectLoopSentinel,
+  LoopTickResolver,
   convertToFunctionResponse,
   createDuplicateProviderToolCallResponse,
   createDebugLogger,
@@ -664,6 +667,13 @@ export class Session implements SessionContext {
   private cronQueue: CronQueueItem[] = [];
   private cronProcessing = false;
   private cronAbortController: AbortController | null = null;
+  // Resolves the `<<loop.md>>` / `<<loop.md-dynamic>>` sentinels at fire time.
+  // Lazily created on the first loop tick; its content cache is reset on
+  // compaction (see #sendMessageStreamWithAutoCompression) and it is rebuilt if
+  // the working dir changes (e.g. /cd) so it always reads the current project's
+  // loop.md.
+  private loopTickResolver: LoopTickResolver | null = null;
+  private loopTickResolverRoot: string | null = null;
   private cronCompletion: Promise<void> | null = null;
   private cronDisabledByTokenLimit = false;
   private lastPromptTokenCount = 0;
@@ -1926,6 +1936,10 @@ export class Session implements SessionContext {
         compressionInfo = compressed;
         this.#recordCompressionTokenCount(compressed);
         if (compressed.compressionStatus === CompressionStatus.COMPRESSED) {
+          // Context was just compacted; a loop.md tick must re-deliver the full
+          // task block (a short reminder refers back to a message that is no
+          // longer in context).
+          this.loopTickResolver?.resetCache();
           const reasonClause =
             compressed.triggerReason === 'image_overflow'
               ? `accumulated enough tool screenshots to trigger compaction for ${this.config.getModel()}`
@@ -2427,6 +2441,20 @@ export class Session implements SessionContext {
     }
   }
 
+  #getLoopTickResolver(): LoopTickResolver {
+    const root = this.config.getWorkingDir();
+    // Rebuild if the working dir changed (e.g. /cd) so loop.md resolves against
+    // the current project; a fresh resolver also correctly re-delivers full.
+    if (!this.loopTickResolver || this.loopTickResolverRoot !== root) {
+      this.loopTickResolver = new LoopTickResolver({
+        projectRoot: root,
+        homeDir: os.homedir(),
+      });
+      this.loopTickResolverRoot = root;
+    }
+    return this.loopTickResolver;
+  }
+
   /**
    * Executes a single cron-fired prompt: echoes it as a user message with
    * `_meta.source='cron'`, streams the model response, and handles tool calls.
@@ -2460,10 +2488,38 @@ export class Session implements SessionContext {
           async () => {
             let turnCount = 0;
             try {
+              // A `<<loop.md>>` / `<<loop.md-dynamic>>` sentinel is expanded at
+              // fire time into the loop.md task block — full on the first or a
+              // changed fire, a short reminder when unchanged. Non-sentinel
+              // prompts pass through untouched.
+              const loopMode = detectLoopSentinel(prompt);
+              const loopTick = loopMode
+                ? await this.#getLoopTickResolver().resolve(loopMode)
+                : null;
+              const modelText = loopTick ? loopTick.modelText : prompt;
+              if (loopTick) {
+                debugLogger.debug(
+                  `loop tick: mode=${loopMode} delivery=${
+                    loopTick.full
+                      ? 'full'
+                      : loopTick.sourcePath
+                        ? 'reminder'
+                        : 'absent'
+                  } path=${loopTick.sourcePath ?? 'none'}`,
+                );
+              }
+              // For a loop tick echo a stable label, never the bare sentinel or
+              // the full task dump; otherwise echo the prompt verbatim.
+              const echoText = loopTick
+                ? loopTick.sourcePath
+                  ? `Loop tick — tasks from ${loopTick.sourcePath}`
+                  : 'Loop tick — loop.md not present'
+                : prompt;
+
               // Echo the cron prompt as a user message so the client sees it
               await this.sendUpdate({
                 sessionUpdate: 'user_message_chunk',
-                content: { type: 'text', text: prompt },
+                content: { type: 'text', text: echoText },
                 _meta: { source: item.source },
               });
 
@@ -2472,7 +2528,7 @@ export class Session implements SessionContext {
               const cronReminders = await this.#buildInitialSystemReminders();
               let nextMessage: Content | null = {
                 role: 'user',
-                parts: [...cronReminders, { text: prompt }],
+                parts: [...cronReminders, { text: modelText }],
               };
 
               while (nextMessage !== null) {
@@ -2501,6 +2557,13 @@ export class Session implements SessionContext {
                   return;
                 }
                 const responseStream = sendResult.responseStream;
+                if (loopTick && turnCount === 1) {
+                  // The block reached the model (the send started); commit it so
+                  // the next tick can detect "unchanged". Deferring the commit
+                  // to here keeps an abort before delivery from poisoning the
+                  // cache into a dangling short reminder.
+                  this.loopTickResolver?.markDelivered();
+                }
                 nextMessage = null;
 
                 for await (const resp of responseStream) {

packages/cli/src/nonInteractiveCli.ts

@@ -25,6 +25,7 @@ import {
   uiTelemetryService,
   parseAndFormatApiError,
   createDebugLogger,
+  detectLoopSentinel,
   SendMessageType,
   restoreWorktreeContext,
   TeamEventType,
@@ -1521,6 +1522,15 @@ export async function runNonInteractive(
               };
 
               scheduler.start((job: { prompt: string; cronExpr?: string }) => {
+                // loop.md sentinel expansion is interactive-only for now; in a
+                // headless run a bare `<<loop.md>>` sentinel would reach the
+                // model as its prompt with no task content, so skip the tick
+                // (no-op) instead of enqueuing it. Full headless loop.md support
+                // is a follow-up.
+                if (detectLoopSentinel(job.prompt)) {
+                  checkCronDone();
+                  return;
+                }
                 const label = job.prompt.slice(0, 40);
                 localQueue.push({
                   displayText: `${job.cronExpr === '@wakeup' ? 'Loop' : 'Cron'}: ${label}`,

packages/core/src/index.ts

@@ -186,6 +186,8 @@ export {
 export * from './services/chatRecordingService.js';
 export * from './services/cronScheduler.js';
 export type { DurableCronTask } from './services/cronTasksFile.js';
+export * from './skills/bundled/loop/loop-task-file.js';
+export * from './skills/bundled/loop/loop-tick-resolver.js';
 export * from './services/fileDiscoveryService.js';
 export * from './services/fileHistoryService.js';
 export * from './services/fileReadCache.js';

packages/core/src/skills/bundled/loop/SKILL.md

@@ -87,4 +87,13 @@ If the interval does not cleanly divide its unit (for example `7m` gives uneven
    - If it is a slash command, invoke it via the Skill tool.
    - Otherwise, act on it directly.
 
+## loop.md task-file mode
+
+Use this when the user wants the loop to work a task list kept in a file (they say "work through my loop.md", "loop over the tasks in .qwen/loop.md", or point at such a file). Tasks live in `.qwen/loop.md` (project) or `~/.qwen/loop.md` (home; project wins). Instead of a natural-language prompt, set the loop's `prompt` to a sentinel so each fire re-reads the file:
+
+- Self-paced (no interval) → LoopWakeup `prompt`: `<<loop.md-dynamic>>`
+- Fixed interval → CronCreate `prompt`: `<<loop.md>>` (with `recurring: true`, and `durable: true` if persistence is implied)
+
+At each fire you receive either the full task list (first delivery, after the file changes, or after a compaction) or a short reminder to keep working the list established earlier. Work the tasks; in self-paced mode re-arm LoopWakeup with `<<loop.md-dynamic>>` only when continued follow-up is useful (same "don't re-arm if complete/blocked" rules as the prompt-only path). If `.qwen/loop.md` is absent at fire time, treat the tick as a no-op. Confirm to the user in plain language ("looping over your `.qwen/loop.md` task list…"), not the raw sentinel.
+
 ## Input

packages/core/src/skills/bundled/loop/SKILL.test.ts

@@ -64,4 +64,13 @@ describe('bundled loop skill', () => {
     expect(body).toContain('**`clear`** — call CronList');
     expect(body).toContain('call CronDelete for every job returned');
   });
+
+  it('documents loop.md task-file mode and the two sentinels', () => {
+    const { body } = loadLoopSkill();
+
+    expect(body).toContain('## loop.md task-file mode');
+    expect(body).toContain('.qwen/loop.md');
+    expect(body).toContain('`<<loop.md-dynamic>>`');
+    expect(body).toContain('`<<loop.md>>`');
+  });
 });